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Preface 



PURPOSE AND SCOPE OF MANUAL 

The RMX/86 Operating System provides software support for 
Intel's iSBC 86/12 single-board computer. It consists of a 
nucleus, terminal handler, debugger and input/output system. 
Each user can configure the operating system to include only 
the features he needs. 



The lOS reference manual is one of four manuals furnishing an 
overview of the RMX/86 Operating System and reference material 
for each of its components. The four manuals ideally should be 
read in the following sequence: 

An Introduction to the RMX/86'"0perating System 980312A 

RMX/86'''Nucleus , Terminal Handler, and Debugger 

Reference Manual 9803122 

RMX/86^n/0 System Reference Manual 9803123 

RMX/86^''System Programmer's Reference Manual 1A2721 

This manual assumes familiarity with concepts and terminology 
introduced in the Nucleus reference manual and with the PL/M 
programming language. It is intended primarily as a quick 
reference to the system calls available in the I/O system. Only 
PL/M calling sequences are shown here. 

Detailed descriptions of I/O system calls are limited to those 
available to applications programmers. Some calls reserved for 
system programmers are discussed generally, but only to give an 
overview of I/O system operation. The latter are described in 
detail in the RMX/86 System Programmer's Reference Manual. 

In the first seven chapters of this manual, system calls are 
named using a generic shorthand (such as CREATE$FILE) or a more 
specific form (such as A$CREATE$FILE for the asynchronous 
version of this call). The actual PL/M external-procedure names 
used to invoke these I/O operations are shown only in Chapter 
8, where the detailed PL/M calling sequences are listed. 

NOTE 

Information in this manual relating to 

stream files, job creation and termination, 

loading jobs, and hybrid/synchronous processing 

describes software that is not included 

in the first release and as such is only 

preliminary and subject to change. 
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Chapter 1. INTRODUCTION TO THE RMX/86 I/O SYSTEM 

The RMX/86 input/output system allows tasks to communicate with 
one another and with the outside world. The I/O system is built 
around the concept of file manipulation, where a "file" can be: 

• a physical device ( physical file), 

■ a data "stream" or pipeline between two or more tasks 
( stream file), or 

■ data or directory information residing on a random- 
access device ( named file). 

Figure 1-1 shows part of a traffic-control application using 
all three kinds of files. This broad interpretation of file 
types makes the RMX/86 I/O system truly device-independent. 

Tasks access the I/O system through various system calls. These 
calls provide numerous file-processing functions, but their 
main roles are: 

s to create, attach, and delete files; 

to read and write files once they are established. 

Other system calls modify file attributes, obtain file status 
information, and perform special device-level functions. Still 
other calls provide auxiliary functions like creating and 
terminating jobs, setting or inspecting job-level default 
parameters, accessing time and date information, and loading 
object files. 

FILE CONNECTIONS 

When a file is created or attached, a connection to that file 
is also established. A file connection is an RMX/86 object that 
contains the means to access the file, a file pointer (in cases 
where the file has been opened for reading or writing), and, in 
some instances, input/output buffers. 

When a task issues a CREATE$FILE, ATTACH$FILE, or 
CREATE$DIRECTORY system call, it receives the token for a file 
connection in return. The task can then supply this token to 
the I/O system to gain access to the file in subsequent 
operations. A file connection, once established, remains valid 
through any number of I/O operations until it is deleted. This 
saves the task considerable overhead; the file does not have to 
be located again each time it is opened or otherwise accessed. 

DEVICES 

A device might be any one of a broad spectrum of physical 
units, such as an I/O terminal, serial input or output unit 
(e.g., paper-tape unit or line printer), or random-access 
storage (e.g., floppy or hard-disk unit). A device might also 
be a thermistor in an oven or a traffic sensor embedded in a 
roadway . 
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Figure 1-1. Task-File Intercommunication For 
Traffic-Monitoring Application 
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In the case of a random-access device, such as a disk drive, 
the device also includes a "volume." A volume is simply the 
physical storage medium used by the particular device (such as 
a diskette or hard disk platter). 

Before a file can be created on a device, the device must be 
attached. When a device is attached, a token for a device 
connection is returned to the caller (normally a system pro- 
gram). This token is used later by applications programs 
creating files on the device. 

FILES 

PHYSICAL FILES 

Some tasks deal directly with physical devices; in fact, some 

tasks deal only with physical devices. For example, a task 

might monitor a sensor continuously and print a message each 
time an event occurs. 

To read the sensor data and write the output message, the task 
must establish physical-file connections to the sensor and 
printer devices. First, the devices must be attached, as men- 
tioned above. The device connections returned are then used as 
parameters in CREATE$FILE system calls. Each call returns a 
physical-file connection to its respective device. 

Using the tokens for these file connections as parameters, the 
task can now issue calls to OPEN the two physical-file con- 
nections, READ from the input connection, and WRITE to the 
output connection. When all I/O operations are completed, the 
file connections can be CLOSED and DELETED. 

STREAM FILES 

Stream files provide a mechanism for intertask communication 
without the use of external devices or media. A stream file is 
useful only when there are both a writer and a reader of the 
stream file, as when the output of one task is connected to the 
input of another. 

To establish a stream-file communication link, the following 
steps are generally required (although the exact protocol can 
vary ) . 

e Call CREATE$FILE to create the stream file and a con- 
nection to the file. 

9 Call ATTACH$FILE to create an additional connection to 
the file. 

c Give one connection to the writing task and the other to 
the reading task; The tasks can then OPEN the con- 
nections for I/O. 
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Multiple readers and/or writers can use the same stream file by 
creating the appropriate set of connections. A read of a stream 
file is a destructive read, however, and such multiple oper- 
ations must be carefully synchronized. 

NAMED FILES 

A named file is a sequence of bytes residing on a random-access 
device. Named files can be either data files or directory 
files. A directory file is a file whose entries are pointers to 
other (data or directory) files. A directory file can also be 
empty . 

Directory Tree 

Each random-access volume supports a tree of directories. Named 
files are components in these hierarchical trees (Figure 1-2). 
A named file is accessed by identifying the device where it 
resides and a path through the tree to which it belongs. As 
Figure 1-2 illustrates, the root of a directory tree is called 
the root directory. The tree's internal nodes are directories; 
its leaves are data files or empty directories. 

The file names shown in this figure are completely arbitrary. 
When a named data or directory file is created, the name speci- 
fied by the creator is automatically cataloged by the I/O 
system in the directory that points to the file. That directory 
is known as the file's parent directory . For example, the 

information needed to access file TUNE SCHED is cataloged in 

its parent directory, TUNEUPS. The information needed to locate 
TUNEUPS is cataloged in directory SERVICE. 

Accessing Named Files 

A named file is accessed by specifying its directory-tree path 
in an I/O system call. 

A directory-tree path has two parts. The first part, or prefix , 
designates the file in the directory tree where the path search 
is to begin. The second part, or subpath , describes the rest of 
the route through the tree to the desired file. The subpath is 
a list of directory names, ending with the name of the file 
being accessed. In Figure 1-2, for example, if the prefix 
designates directory SERVICE, the subpath to file 80_PART_LIST 
is 

TUNEUPS/PARTS/80_PART_LIST 

A subpath can also be null, in which case the prefix itself 
designates the target file. 

The exact syntax for prefix, subpath, and file-name specifi- 
cation is described in Chapter 8, where calling sequences are 
covered in detail. 
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Figure 1-2. Directory Tree For Auto Dealership Application 
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File-Access Protection 

The creator of a named file can limit access rights to the file 
for himself and other users. The I/O system provides file- 
access protection by combining the concepts of a user object 
and an access list. 

Each user of the I/O system is associated with a user object 
that identifies not only that user, but also all groups to 
which he belongs (engineering team, quality assurance com- 
mittee, etc.). These objects are designated in I/O system calls 
by a token or, in the H$CHANGE$ACCESS and S$CHANGE$ACCESS 
calls, by the logical name "WORLD," which signifies all users 
of the system. 

The specific access rights allowable are; 

Named Data Files Named Directory Files 

Delete Delete 

Read Display 

Append Add Entry 

Update Change Entry 

When a named file is created by an A$CREATE$FILE or 
A$CREATE$DIRECTORY system call, the creator specifies the token 
for his user object and a byte mask describing the (combination 
of) access right(s) to be granted. The access mask may later be 
changed or more users granted access by calling A$CHANGE$ACCESS 
(up to a total of three "user/access" pairs per file). When the 
file is subsequently accessed, the I/O system compares the 
specified user-id value with the user/access list for the file 
to see if that value is present and has the requested access 
privilege . 

When a named file is created by a call to H$CREATE$FILE , 
H$CREATE$DIRECTORY, S$CREATE$FILE , or S$CREATE$DIRECTORY , the 
global user "WORLD" is assumed and full access rights are 
granted automatically. The rights can be limited by subsequent 
calls to H$CHANGE$ACCESS or S$CHANGE$ACCESS , but the user 
object is still "WORLD." 

As this discussion of file protection indicates, the I/O system 
frequently offers several system calls to perform the same 
function. The following section describes these options in more 
detail . 

THREE LEVELS OF SYSTEM CALLS 

At the beginning of this chapter, the distinction was made 
between file-related system calls (that create, modify, delete, 
inspect, or perform I/O on files) and auxiliary system calls 
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(that create jobs, set job defaults, access time/date 
information, and load object files). In the case of file- 
related system calls, the I/O system provides three levels of 
operation . 

• asynchronous 

hybrid (partially asynchronous, partially synchronous) 

synchronous 

In a real-time environment, the events that trigger system 
response usually happen at unpredictable times and in an unpre- 
dictable sequence. That is, they happen asynchronously. The 
controller of the system is responsible for synchronizing these 
events . 

At the asynchronous level of I/O operation, the controller of 
the system is the applications programmer. The programmer must 
be familiar with techniques for synchronizing his I/O oper- 
ations, primarily using mailboxes (as described in the RMX/86 
Nucleus, Terminal Handler and Debugger Reference Manual ) . The 
advantages of this most basic level of I/O operation are that 
it requires the least system memory of the three options, it 
gives the programmer the greatest flexibility in specifying 
system call parameters, and it allows the programmer to perform 
other operations in parallel with the asynchronous I/O oper- 
ations . 

At the hybrid level, many operations are synchronized auto- 
matically, simplifying the programmer's role. System calls are 
simplified also, as defaults are assumed for some parameters 
and response mailboxes are not needed. Where they are required, 
user objects and file-connection objects can be given logical 
names that can be specified instead of 16-bit tokens in system 
call parameters. The file connections created at this level are 
fully compatible with those created asynchronously, allowing 
the hybrid level to perform I/O on established data-file con- 
nections using asynchronous calls, and thus retain some of the 
flexibility of the asynchronous level. 

At the synchronous level, all operations are synchronized 
automatically by the I/O system, relieving the programmer of 
this burden completely. System calls are simplified, as at the 
hybrid level, and the logical-naming capability exists at the 
synchronous level also. In addition, I/O buffers built into 
data-file connections allow automatic overlapping of I/O oper- 
ations, making this level particularly efficient for processing 
sequential data. The automatic buffering' also provides blocking 
and deblocking of I/O data, usually resulting in increased 
device throughput. The expense of this programming convenience 
is the greater system memory required for the synchronous 
level, and the inability to specify arbitrary buffering and 
synchronizing. 
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MANUAL ORGANIZATION 

Chapters 2-4 describe these three levels of file operations in 
more detail and summarize the system calls available at each 
level. Chapters 5-7 summarize the system calls available for 
performing auxiliary functions. Chapter 8 provides the detailed 
PL/M calling sequences for every I/O system call available to 
the applications programmer. 
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Chapter 2. ASYNCHRONOUS INPUT/OUTPUT 

Asynchronous operations represent the most basic level of 
RMX/86 I/O. While this level provides fewer features than the 
hybrid and synchronous levels, it does allow the programmer 
greater flexibility in specifying parameters and in performing 
multiple I/O operations simultaneously. The programmer must 
synchronize these operations himself, using result segments 
returned to mailboxes designated in asynchronous system calls. 
Asynchronous I/O processing also requires the least system 
memory of these three levels. 

This chapter provides an overview of asynchronous system calls. 
The detailed PL/M calling sequences and descriptions of these 
calls can be found in Chapter 8. Not every system call is 
applicable for every kind of file, as indicated in the fol- 
lowing summaries. 

CALLS THAT CREATE FILE CONNECTIONS 

Three system calls are available for creating connections at 
the asynchronous level: 

9 A$CREATE$FILE 
IB A$ATTACH$FILE 
9 A$CREATE$DIRECTORY 

CREATING A DATA FILE CONNECTION 

The A$CREATE$FILE system call returns a connection to a physi- 
cal, stream, or named data file. If the file does not yet 
exist, this call also creates the file. If the file already 
exists, several options are available to the caller, as 
detailed in Chapter 8. 

ATTACHING A FILE 

The A$ATTACH$FILE system call creates a connection to an ex- 
isting file. Once the connection is formed, it remains in 
existence until it is deleted, or until the creating task is 
deleted . 

CREATING A DIRECTORY FILE 

The A$CREATE$DIRECTORY system call applies to named directory 
files only. This call creates a new directory file and returns 
a connection to that file. 

CALLS THAT MODIFY FILE CONNECTIONS 

The asychronous level has two calls that modify file 
connections : 

• A$CHANGE$ACCESS 
i A$RENAME$FILE 
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CHANGING FILE ACCESS RIGHTS 

The A$CHANGE$ACCESS system call applies to named files only. It 
is called to change the access rights to a named data or direc- 
tory file. 

RENAMING A FILE 

The A$RENAME$FILE system call applies to named files only. It 
is called to change the name of a file. A renamed data file can 
also be recataloged in a different parent directory, so long as 
that directory is on the same volume as the file's original 
parent, but a directory file can only be renamed within its 
parent directory. 

CALLS THAT OBTAIN FILE INFORMATION 

The asynchronous level has four calls that obtain status and 
attribute information about files and their connections: 

® A$GET$CONNECTION$STATUS 

@ A$GET$FILE$STATUS 

e A$GET$DIRECTORY$ENTRY 

A$GET$PATH$COMPONENT 

GETTING CONNECTION STATUS DATA 

The A$GET$CONNECTION$STATUS system call returns information on 
the current status of one specific connection to a file. 

GETTING FILE STATUS DATA 

The A$GET$FILE$STATUS system call returns status and attribute 
information about a specific file and its connections. The form 
of the information differs for physical, stream, and named 
files. 

GETTING DIRECTORY CONTENTS 

The A$GET$DIRECTORY$ENTRY system call applies to named files 
only. 

Entries in a directory are numbered sequentially starting from 
zero. By specifying an entry number in a call to 
A$GET$DIRECTORY$ENTRY, the caller can obtain the name of the 
file associated with that entry. 

GETTING A PATH COMPONENT 

The A$GET$PATH$COMPONENT system call is meaningful for named 
files only. The user who knows the token for a file connection 
can specify this token to A$GET$PATH$COMPONENT and receive the 
name of the file. This is the name by which it is cataloged in 
its parent directory. 
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If the specified token belongs to the root directory of a 
directory tree, a null string is returned because a root direc- 
tory has no parent. A null string is also returned if the token 
for a physical or stream file is specified. 

CALLS THAT PERFORM FILE I/O 

Calls that perform file I/O are valid only for data files (not 
for directory file connections). Five such calls are available 
at the asynchronous level. 

® A$OPEN 

6 A$SEEK 

® A$READ 

6 A$WRITE 

(9 A$CLOSE 

Buffers used in read/write operations must be in a segment 
allocated by the free-space manager of the RMX/86 nucleus (that 
is, the segment must be allocated dynamically). 

OPENING A DATA-FILE CONNECTION 

The A$OPEN system call opens a file connection for input/output 
and specifies who, if anyone, may share the connection 
(readers, writers, or both). Opening a file connection also 
establishes a file pointer set to byte position zero. A$SEEK, 
A$READ, and A$WRITE all move this pointer. 

MOVING THE FILE POINTER 

The A$SEE-K system call applies to physical and named data files 
only. It is called to move the file pointer for an open con- 
nection, thus allowing file data to be accessed randomly. The 
file pointer can be placed at any byte position in the file. 

READING A FILE 

The A$Read sytem call initiates reading via an open file con- 
nection. The connection is read as a string of bytes, and any 
number of bytes can be requested. The bytes are read starting 
at the current setting of the file pointer. Following the read 
operation, the file pointer is positioned just past the last 
byte read. 

WRITING A FILE 

The A$WRITE system call initiates a write operation from a user 
buffer into a connected file. The data is written beginning at 
the current setting of the file pointer. Following the write 
operation, the file pointer is positioned just after the last 
byte written. 
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CLOSING A DATA-FILE CONNECTION 

The A$CLOSE system call is invoked to close an open connection 
when I/O operations are completed. A closed connection can be 
reopened without attaching the file again. 

A CALL TO PERFORM A DEVICE-LEVEL FUNCTION 

The asynchronous level includes an A$SPECIAL system call to 
perform special device-level functions. This call applies to 
physical files only. 

The I/O system supports a number of functions at the device 
level (namely read, write, seek, attach device, detach device, 
open, and close). The A$SPECIAL system call allows the user to 
perform additional device-driver functions. For example, a 
rewind function would be desirable for a magnetic tape driver 
or a track formatting function for a random-access device. 

CALLS THAT DELETE INFORMATION, FILES, AND CONNECTIONS 

The asynchronous level has three calls that delete files (or 
part of a file) and connections. 

A$DELETE$FILE 

© A$TRUNCATE 

A$DELETE$CONNECTION 

DELETING A FILE 

The A$DELETE$FILE system call applies to stream and named files 
only. When called, it marks the designated file for deletion. 
The file is not actually deleted, however, until all con- 
nections to the file have been severed. Directory files cannot 
be deleted unless they are empty. 

TRUNCATING A FILE 

The A$TRUNCATE system call applies to named data files only. It 
truncates a file by freeing all allocated bytes beyond the 
current setting of the file pointer. A seek operation can be 
used to position the file pointer before the call to 
A$TRUNCATE. Truncation is performed immediately. If the file 
pointer is positioned at or beyond the end-of-file, no oper- 
ation is performed. 

DELETING A CONNECTION 

The A$DELETE$CONNECTION system call severs a file connection 
established by A$CREATE$FILE , A$ATTACH$FILE , or A$CREATE$- 
DIRECTORY. If a connection is open when this call is made, the 
connection is closed before being severed. 

A$DELETE$CONNECTION also deletes the file associated with the 
specified connection if the file is both marked for deletion 
(by a previous call to A$DELETE$FILE) and the specified con- 
nection is the last remaining connection to the file. 
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Chapter 3. HYBRID INPUT/OUTPUT 

The hybrid level of I/O system calls is an extension of the 
asynchronous level described in Chapter 2. At this level, calls 
that create and delete files and connections, calls that modify 
file attributes, and certain status calls have synchronous 
interfaces. This means the programmer does not have to syn- 
chronize these operations himself. The calling sequences are 
simplified also. Logical names can be specified for path 
prefixes, default user objects are assumed, and no response 
mailbox need be specified since the programmer does no 
synchronizing. These synchronous system calls require more 
system memory than their asynchronous counterparts, however. 

File connections created at the hybrid level are fully compat- 
ible with those created by asynchronous system calls. This 
allows the hybrid-level user to invoke asynchronous calls for 
file I/O and related operations, thereby retaining most of the 
flexibility of asynchronous input/output. 

This chapter provides an overview of hybrid system calls. The 
detailed PL/M calling sequences and descriptions of these calls 
can be found in Chapter 8. Not every system call is applicable 
for every kind of file, as indicated in the following summaries. 

CALLS THAT CREATE FILE CONNECTIONS 

Three system calls are available for creating file connections 
at the hybrid level: 

O H$CREATE$FILE 
» H$ATTACH$FILE 
s H$CREATE$DIRECTORY 

CREATING A DATA FILE CONNECTION 

The H$CREATE$FILE system call returns a connection to a phys- 
ical, stream, or named data file. The connection can also be 
given a logical name, under which it is cataloged in the job's 
logical-name directory. 

If the file does not yet exist, this call also creates a new 
file. If the file already exists, several options are available, 
to the caller, as detailed in Chapter 8. 

ATTACHING A FILE 

The H$ATTACH$FILE system call creates a connection to an exist- 
ing file. The connection can also be given a logical name, 
under which it is cataloged in the job's logical-name directory. 

CREATING A DIRECTORY FILE 

The H$CREATE$DIRECTORY system call applies to named directory 
files only. This call creates a new directory file and returns 
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a connection to that file. The connection can also be given a 
logical name, under which it is cataloged in the job's logical- 
name directory . 

CALLS THAT MODIFY FILE ATTRIBUTES 

The hybrid level has two calls that modify file attributes: 

© H$CHANGE$ACCESS 
© H$RENAME$FILE 

CHANGING FILE ACCESS RIGHTS 

The H$CHANGE$ACCESS system call applies to named files only. It 
is called to change the access rights to a named data or direc- 
tory file. 

RENAMING A FILE 

The H$RENAME$FILE system call applies to named files only. It 
is called to change the name of a file. The name changed is. the 
subpath name cataloged in the file's parent directory, not the 
logical name cataloged in the job's logical-name directory. 

A renamed data file can be recataloged in a different parent 
directory, so long as that directory is on the same volume as 
the file's original parent. A directory file can only be re- 
named within its parent directory. 

CALLS THAT OBTAIN FILE INFORMATION 

The hybrid level has two calls that obtain status and attribute 
information about files and their connections: 

© H$GET$FILE$STATUS 

© H$LOOK$UP$CONNECTION 

GETTING FILE STATUS DATA 

The H$GET$FILE$STATUS system call returns status and attribute 
information about a specific file and its connections. The form 
of the information differs for physical, stream, and named 
files. 

GETTING THE TOKEN FOR A CONNECTION 

The H$LOOK$UP$CONNECTION system call returns the token for the 
file connection associated with a specified logical name. 

CALLS THAT DELETE FILES AND CONNECTIONS 

The hybrid level has two system calls that delete files and 
connections: 

@ H$DELETE$FILE 

® H$DELETE$CONNECTION 
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DELETING A FILE 

The H$DELETE$FILE system call applies to stream and named files 
only. When called, it marks the designated file for deletion. 
The file is not actually deleted, however, until all con- 
nections to the file have been severed. Directory files cannot 
be deleted unless they are empty. 

DELETING A CONNECTION 

The H$DELETE$CONNECTION system call severs a file connection 
established by H$CREATE$FILE , H$ATTACH$FILE , or H$CREATE$- 
DIRECTORY. If the connection is open when this call is made, 
the connection is closed before being severed. The logical name 
for the connection, if one exists, is removed from the job's 
logical-name directory. 

H$DELETE$CONNECTION also deletes the file associated with the 
specified connection if the file is both marked for deletion 
(by a previous call to H$DELETE$FILE) and the specified con- 
nection is the last remaining connection to the file. 

ASYNCHRONOUS CALLS USED AT THE HYBRID LEVEL 

The hybrid level uses many of the asynchronous system calls 
described in Chapter 2. The calls operate on established file 
connections to perform file I/O, obtain connection status or 
attribute information, or perform special device-level 
functions. 

Ten asynchronous calls are supported at the hybrid level: 

9 A$OPEN 

9 A$CLOSE 

e A$SEEK 

e A$READ 

o A$WRITE 

9 A$TRUNCATE 

® A$SPECIAL 

9 A$GET$DIRECTORY$ENTRY 

9 A$GET$PATH$COMPONENT 

9 A$GET$CONNECTION$STATUS 

These calls perform the same operations described in Chapter 2 
(and in detail in Chapter 8). 
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Chapter 4. SYNCHRONOUS INPUT/OUTPUT 

Synchronous operations represent the highest level of RMX/86 
I/O. All calls at this level are synchronized automatically. 
PL/M calling sequences are simplified compared to asynchronous 
calls. Logical names can be specified for path prefixes, de- 
fault user objects are assumed, and no response mailboxes need 
be specified since the programmer does no synchronizing. 

Synchronous calls that create or open a data-file connection 
can also specify up to two buffers as part of that connection. 
These synchronous I/O system (SIOS) buffers allow overlapping 
of read and write operations. Data can be read into a buffer in 
anticipation of task requirements, or can be written from a 
buffer while the task is preparing additional output. When two 
SIOS buffers are used, the I/O system can begin the next read 
before processing on the current buffer is completed; sim- 
ilarly, it can begin writing out a full buffer while the other 
buffer is being filled. This makes the synchronous level 
especially efficient at processing sequential data. 

As these features indicate, the synchronous level provides the 
most convenient tool for I/O processing of the three levels 
available, but it also requires the most system memory. 

This chapter provides an overview of synchronous system calls. 
The detailed PL/M calling sequences and descriptions of these 
calls can be found in Chapter 8. Not every system call is 
applicable to every kind of file, as indicated in the following 
summaries . 

CALLS THAT CREATE FILE CONNECTIONS 

Three system calls are available for creating file connections 
at the synchronous level: 

S$CREATE$FILE 

• S$ATTACH$FILE 

• S$CREATE$DIRECTORY 

CREATING A DATA FILE CONNECTION 

The S$CREATE$FILE system call returns a connection to a phys- 
ical, stream, or named data file. This composite connection 
includes any SIOS buffers requested in the call. The buffer 
size specified in this call is the default buffer size, which 
can be overridden by S$OPEN when the connection is opened. The 
connection returned by S$CREATE$FILE can also be given a 
logical name and cataloged in the job's logical-name directory 
under this name. 

If the designated file does not yet exist, this call also 
creates the file. If the file already exists, several options 
are available to the caller, as detailed in Chapter 8. 
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ATTACHING A FILE 



The S$ATTACH$FILE system call creates a connection to an 

existing file, including any desired SIOS buffers. As with 

S$CREATE$FILE , the buffer size specified is the default size, 

which can be overridden by S$OPEN. 



The connection returned by this call can also be given a 
logical name, under which it is cataloged in the job's logical- 
name directory. 

CREATING A DIRECTORY FILE 

The S$CREATE$DIRECTORY system call applies to named directory 
files only. This call creates a new directory file and returns 
a connection to that file. The connection can also be given a 
logical name, under which it is cataloged in the job's logical- 
name directory. 

CALLS THAT MODIFY FILE ATTRIBUTES 

The synchronous level has two calls that modify file attributes: 

S$CHANGE$ACCESS 
9 S$RENAME$FILE 

CHANGING FILE ACCESS RIGHTS 

The S$CHANGE$ACCESS system call applies to named files only. It 
is called to change the access rights to a named data or direc- 
tory file. 

RENAMING A FILE 

The S$RENAME$FILE system call applies to named files only. It 
is called to change the name of a file. The name changed is the 
subpath name cataloged in the file's parent directory, not the 
logical name cataloged in the job's logical-name directory. 

A renamed data file can also be recataloged in a different 
parent directory, so long as that directory is on the same 
volume as the file's original parent, but a directory file can 
only be renamed within its parent directory. 

CALLS THAT OBTAIN FILE INFORMATION 

The synchronous level has three calls that obtain status and 
attribute information about files and their connections. 

e S$GET$CONNECTION$STATUS 
S$GET$FILE$STATUS 
• S$LOOK$UP$CONNECTION 
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GETTING CONNECTION STATUS DATA 

The S$GET$CONNECTION$STATUS system call returns information on 
the current status of one specific connection to a file. 

GETTING FILE STATUS DATA 

The S$GET$FILE$STATUS system call returns status and attribute 
information about a specific file and its connections. The form 
of the information differs for physical, stream, and named 
files . 

GETTING THE TOKEN FOR A CONNECTION 

The S$LOOK$UP$CONNECTION system call returns the token for the 
file connection associated with a specified logical name. 

CALLS THAT PERFORM FILE I/O 

Calls that perform file I/O are valid only for data files (not 
for directory file connections). Seven such calls are available 
at the synchronous level: 

® S$OPEN 

® S$SEEK 

@ S$READ$MOVE 

IB S$READ$LOCATE 

® S$WRITE$UPDATE 

9 S$CLOSE 

OPENING A DATA-FILE CONNECTION 

The S$OPEN system call opens a file connection for input/output 
and specifies who may share the connection (readers, writers, 
or both). Opening a file also establishes a file pointer set to 
byte position zero and, if the file is being opened for read- 
ing, initiates the first read operation. 

S$OPEN can also request up to two SIOS buffers for the open 
connection and specify their size, if the size differs from 
that specified when the connection was created. 

MOVING THE FILE POINTER 

The S$SEEK system call applies to physical and named data files 
only. It is called to move the file pointer for an open con- 
nection, thus allowing file data to be accessed randomly. The 
file pointer can be placed at any byte position in the file. 

READING TO A CALLER BUFFER 

The S$READ$MOVE system call moves a collection of bytes from a 
file to a specified caller buffer. 
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Reading to an SIOS Buffer 

The S$READ$LOCAtE system call reads a collection of bytes from 
a designated file to an SIOS buffer. When the read operation 
has been completed, S$READ$LOCATE returns the location of the 
buffer. 

WRITING FROM A CALLER BUFFER 

The S$WRITE$MOVE system call writes a collection of bytes from 
a designated caller buffer to a file. 

UPDATING A FILE 

As mentioned above, S$READ$LOCATE returns the location of the 
data it reads (that is, a pointer to an SIOS buffer). The 
S$WRITE$UPDATE system call references this pointer to write the 
data back to its original location after it has been updated. A 
call to S$READ$LOCATE must be the most recent operation on the 
connection addressed by S$WRITE$UPDATE. 

CLOSING A DATA-FILE CONNECTION 

The S$CLOSE system call closes an open connection. Before 
closing the connection, this call waits for all I/O operations 
in progress on the file to be completed, makes sure that all 
data in the buffer of an output file is written, and releases 
the SIOS buffers created by S$OPEN. 

A CALL TO PERFORM A DEVICE-LEVEL FUNCTION 

The synchronous level includes an S$SPECIAL system call to 
perform special device-level functions. This call applies to 
physical files only. 

The I/O system supports a number of functions at the device 
level (namely read, write, seek, attach device, detach device, 
open, and close). The S$SPECIAL system call allows the user to 
perform additional device-driver functions. For example, a 
rewind function would be desirable for a magnetic tape driver 
or a track formatting function for a random-access device. 

CALLS THAT DELETE FILES AND CONNECTIONS 

The synchronous level has three calls that delete files (or 
part of a file) and connections: 

e S$DELETE$FILE 

• S$TRUNCATE$FILE 

• S$DELETE$CONNECTION 

DELETING A FILE 

The S$DELETE$FILE system call applies to stream and named files 
only. When called, it marks the designated file for deletion. 
The file is not actually deleted, however, until all connections 
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to the file have been severed. Directory files cannot be de- 
leted unless they are empty. 

TRUNCATING A FILE 

The S$TRUNCATE$FILE system call applies to named data files 
only. It truncates a file by freeing all allocated bytes beyond 
the current setting of the file pointer. A seek operation can 
be used to position the file pointer before the call to the 
S$TRUNCATE$FILE . Truncation is performed immediately. If the 
file pointer is positioned at or beyond the end~of-file , no 
operation is performed. 

DELETING A DATA-FILE CONNECTION 

The S$DELETE$CONNECTION system call severs a file connection 
established by S$CREATE$FILE or S$ATTACH$FILE . If the con- 
nection is open when S$DELETE$CONNECTION is called, it is 
closed before being severed. The logical name for the con- 
nection, if one exists, is removed from the job's logical name 
directory . 

S$DELETE$CONNECTION also deletes the file associated with the 
specified connection if the file is both marked for deletion 
(by a previous call to S$DELETE$FILE) and the specified con- 
nection is the last remaining connection to the file. 
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Chapter 5. THE JOB ENVIRONMENT 

A job is an environment for tasks. It includes not only the 
task(s) to be executed, but also the resources needed by the 
tasks(s). These include: 

9 memory 

exchanges (mailboxes and semaphores) 

directories 

9 other objects, such as connections 

Each of these job components is described in the RMX/86 
Nucleus, Terminal Handler, and Debugger Reference Manual. 

The six job-related system calls described in this chapter fall 
into two categories: 

8 system calls that create or terminate jobs 

9 system calls that set or inspect the default user and 
prefix for a job 

CREATING AND TERMINATING JOBS 

Once a job exists, its tasks can create other jobs. These jobs 
become the children of the creating (parent) job. 

In the I/O system, jobs are created by invoking the 
CREATE$IO$JOB system call. This call creates both a job and its 
first task. It also includes several parameters useful for I/O 
processing. These parameters can specify a default user, a 
default path prefix, and a pointer to a list of logical names 
to be used by the job. CREATE$IO$JOB also specifies a mailbox 
to be used for parent-child job communication. 

The EXIT$IO$JOB system call causes the calling task to term- 
inate and notifies the parent job through the mailbox 
established by CREATE$I0$JOB. 

EXIT$IO$JOB performs the following operations: 

deletes all connections and detaches all logical devices 
attached by the job; 

• creates a segment containing the exit message; 

e sends the exit message to the mailbox provided by the 
parent job; 

• deletes the calling task. 

The parent job can then delete the current job, if it wishes to 
do so. 

DEFAULT USER 

When a named file is created, its creator is identified as the 
owner of the file. 
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The token for the owner's user object is a required parameter 
in many asynchronous system calls. The programmer can specify a 
default user for the entire job, however, simplifying parameter 
specification considerably. Once the default has been estab- 
lished asynchronous calls merely specify a zero wherever the 
user parameter is required. Hybrid and synchronous system calls 
simplify user specification even further by always assuming the 
default user. 

We mentioned above that CREATE$IO$JOB can be used to specify a 
default user at the time a job is created. The SET$DEFAULT$USER 
system call can be invoked to establish a default user for the 
current job, or another job that already exists. 

A given job's default user can be determined at any time by 
calling GET$DEFAULT$USER. 

DEFAULT PREFIX 

Many of the system calls described in Chapters 2-A require a 
path prefix as a parameter (even if a subpath is not needed). 
Asynchronous calls require the token for a device connection or 
a file connection as a prefix. Hybrid and synchronous calls 
accept a logical name as the prefix designator. 

Prefix specification can be simplified by establishing a de- 
fault prefix for the job. Once the default is established, 
asynchronous calls need only specify a zero to designate the 
prefix parameter. Hybrid and synchronous calls can omit the 
path prefix entirely, in which case the default is assumed. 

Setting a default prefix also locates a job within a directory 
tree. Subsequent references to files used by the job occur 
relative to the default directory associated with the job. 

When a job is created, the default prefix can be set by a 
parameter of the CREATE$IO$JOB system call. The 
SET$DEFAULT$PREFIX system call can be invoked to establish the 
default prefix for the current job, or for another job that 
already exists. 

A given job's default prefix can be determined at any time by 
calling GET$DEFAULT$PREFIX. 
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Chapter 6. TIME AND DATE FUNCTIONS 

The time and date functions are part of the I/O system, but 
they are also separately configurable, for applications that 
may want to use them without the I/O system. 

The time/date is maintained as a 32-bit counter containing the 
number of seconds since midnight, January 1, 1978. The I/O 
system supports two system calls for accessing this counter: 

GET$TIME 

e GET$TIME$STRING 

GET$TIME returns the time/date value as it is stored internally 
(that is, as the total seconds since January 1, 1978). 

GET$TIME$STRING returns this information in more readable form. 
The time is returned in the format. 

HH:MM:SS (hour :minute : second) 

and the date in the format 

MM/DD/YY (month/day /year) 
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Chapter 7. RMX/86 LOADER 

The RMX/86 loader utility is called to load an object file into 
memory . 

The loader can also be instructed to create a new job and in 
addition, can create a task to execute the code from the object 
file once loading is complete. 

Object files must be located by L0C86 before they can be 
loaded. That is, load addresses must be specified as absolute 
memory addresses. 

LOADER OPERATION 

The system call invoked to load object files is S$LOAD (Syn- 
chronous load). This call can perform any of the following 
function combinations: 

® Create a job, load a file, and create a task; 

© Create a job and load a file; 

® Load a file and create a task; 

® Load a file. 



CREATING A JOB 

When a caller asks the loader to create a job, the loader 
invokes the CREATE$IO$JOB system call (described in Chapter 5). 
This gives the loaded task the ability to call EXIT$IO$JOB to 
terminate itself when finished. 

By creating a job for the loaded task, the caller can control 
the minimum and maximum memory used by tasks in the job. These 
two parameters are specified as part of the call to the loader. 

PACKAGE. OBJECT 



The loader creates a special package object to simplify passing 
results returned by the load call. The package object allows 
several other objects' tokens to be "packaged" and returned as 
a single object, the token for the package. 

To expand the contents of a package object, the user must 
specify its token to the INSPECT$PACKAGE system call. This call 
returns a set of tokens for the package object. 



The DELETE$PACKAGE system call can 
package object. 



be invoked to delete 
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Chapter 8. INVOKING I/O SYSTEM CALLS IN PL/M 

This chapter describes the PL/M calling sequences to RMX/86 I/O 
system calls. The list is limited to calls that can be invoked 
from application programs. I/0-related calls reserved for 
system programmers (that is, calls that can affect an entire 
system) are described in the RMX/86 System Programmer's 
Reference Manual . 

The system calls are listed here alphabetically by the same 
shorthand notation used throughout this manual. For example, 
S$DELETE$FILE refers to the synchronous-level delete-file 
system call and appears alphabetically before 
SET$DEFAULT$PREFIX. This notation is language independent and 
should not be confused with the actual form of the PL/M call. 
The precise format of each call is spelled out as part of its 
detailed description. 

SYNTAX NOTATION 

RMX/86 I/O operations are declared as typed or untyped external 
procedures by PL/M. These procedure declarations are shown in 
Appendix B. PL/M performs I/O operations by issuing external 
procedure calls. 

Certain conventions are used in this chapter to describe the 
PL/M calling sequences. Calls can be entered using either 
upper-cased or lower-cased characters, but in this chapter PL/M 
reserved words (such as CALL) and procedure names (such as 
RQ$A$READ) are shown in capital letters. Lower-cased items 
represent input parameters to be replaced with actual values 
when the I/O procedure is called. Input parameters are sep- 
arated by commas and the entire parameter list is enclosed in 
parentheses. A lower-cased item to the left of an equal ( = ) 
sign in a typed procedure call represents a value returned by 
the call. Procedure calls are terminated by a semicolon. 

EXAMPLES 

1. connection = RQ$H$CREATE$FILE (log$name, path): 

This sequence calls the hybrid-level create-file typed 

procedure, specifying as input parameters a logical name 

for the connection being created and the path to the new 

file. The call returns a new file connection to the 
caller . 

2. CALL RQ$S$TRUNCATE$FILE (connection): 

This sequence calls the synchronous-level truncate-file 
untyped procedure, specifying a connection to the file 
being truncated as its input parameter. 
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INPUT PARAMETER SPECIFICATION 

USER PARAMETER 

This parameter is specified only in asynchronous sytem calls. 
It contains a 16-bit token designating the caller's user 
object. A zero specification designates the default user. 
Hybrid and synchronous system calls always assume the default 
user. 

LOGICAL-NAME PARAMETER 

This parameter is specified only in hybrid and synchronous 
system calls. It designates the logical name under which a new 
file connection is to be cataloged in the job's logical-name 
directory. A logical name can be 1-12 ASCII characters, 
including any printable ASCII character except the colon (:), 
slash (/), and up-arrow (|) or cirumflex ("). This parameter 
can also be specified as a zero, in which case the new file 
connection is not cataloged in the logical-name directory. 

FILE-PATH PARAMETER(S) 

Files are designated in system calls by specifying their path , 
that is, their prefix and subpath . For named files, the prefix 
designates the starting point in a directory-tree scan and the 
subpath describes the rest of the route through the tree to the 
desired file. Since physical and stream files are not nodes in 
a directory tree, the subpath parameter has no meaning for 
them. The prefix designates the desired connection directly for 
these files. 

Path Specification in Asynchronous Calls . 

Asynchronous system calls specify paths using two parameters. 
The prefix parameter is a token designating an existing device 
connection or file connection. If this parameter is zero, the 
default prefix is assumed. 

For named files, the subpath parameter is a pointer to an ASCII 
string. The form of this string is described below. The subpath 
can also be zero or can point to a null string, in which case 
the prefix points directly to the desired connection. For 
physical and stream files, the subpath parameter is always 
specified as zero. 

Asynchronous system calls can specify paths in the following 
forms: 

Meanin g 
Default prefix is desired connection. 
Token points to desired connection. 
Token points to desired connection. 

Token plus ASCII string lead to 
desired connection. 
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Pointer to 




Null String 
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The subpath ASCII string is a list of file names separated by 
slashes, terminating with the desired file. A file name can be 
1-14 ASCII characters, including any printable ASCII character 
except the slash (/) and up-arrow (|) or circumflex ("). In 
Figure 8-1, for example, if the prefix is the token for direc- 
tory OBSTETRICS and we wish to reference file OUT__PATIENT , the 
subpath parameter must point to the string 

DELIVERY/POST_PARTUM/OUT_PATIENT 

If the ASCII string begins with a slash, the prefix merely 
designates the tree and the subpath is assumed to start at the 
root directory of the tree associated with the prefix. For 
example, if the prefix designates directory GYNECOLOGY in 
Figure 8-1, the subpath to OUT$PATIENT is 

/OBSTETRICS/DELIVERY/POST PARTUM/OUT PATIENT 



OBSTETRICS 



GYNECOLOGY 



ROOT 
DIRECTORY 



PRENATAL 



IN-LABOR 



POST-PARTUM 




EMPTY 
DIRECTORY 



EMPTY 
DIRECTORY 



IN-PATIENT 



OUT-PATIENT 





Figure 8-1. Sample Directory Tree (Asynchronous Call) 
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Files can also be addressed relative to other files in the 
tree, using "4" as a path component. The "j" refers to the 
parent directory of the current file in the path scan. For 
example, now that we have a connection to OUT__PATIENT in Figure 
8-1, we can use that connection to specify a subpath to IN 
PATIENT. With the token for the OUT__PATIENT connection as our 
prefix, the subpath string would be 

llN_PATIENT 
Note that no slash follows the "4" in this example; "4" itself 
can be a separator. 

Of course an even simpler approach would be to designate direc- 
tory POST_PARTUM as the prefix, in which case the ASCII string 
becomes 

IN_PATIENT 

Path Specifications in Hybrid/Synchronous Calls 

Hybrid and synchronous system calls specify the path as a 
single parameter, a pointer to an ASCII string. The ASCII 
string encompasses both the prefix and subpath. 

The prefix can be specified using the logical name of the 
designated connection. The logical name must be enclosed in 
colons when it appears in the path string. If no name is speci- 
fied, the default prefix is assumed. 

The subpath is a list of file names separated by slashes, as 
defined for asynchronous calls above. A slash at the beginning 
of this list designates the root directory associated with the 
prefix. The up arrow (4) character can be used to designate the 
parent directory of the current file in the scan. 

The ASCII string addressed in hybrid and synchronous system 
calls can take any of the following forms: 

ASCII String Meaning 

null Default prefix is desired connection. 

:log-name: Name designates desired connection, 

subpath Tree scan starts at default prefix, 

/subpath Tree scan starts at root directory 

associated with default prefix. 
;log$name :/subpath Tree scan starts at root directory 

associated with file designated by 

logical name. 
: log$name isubpath Tree scan starts at file designated 

by logical name. 

Figure 8-2 is the same as Figure 8-1, except that logical names 
(shown enclosed in colons) have been added for each directory 
and data file. Referring to this figure, file OUT__PATIENT might 
be addressed by any of the following strings (assuming 
OBSTETRICS as the default prefix): 
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:HOME: (assuming this connection already exists) 

DELIVERY/PGST_PARTUM/OUT_PATIENT 

/OBSTETRICS/DELIVERY/POST_PARTUM/OUT_PATIENT 

;GYN: /OBSTETRICS/DELI VERY/POST_PARTUM/OUT_PATIENT 

:POST:OUT_PATIENT 

:HOSP: | OUT_PATIENT 

RESPONSE MAILBOX PARAMETER 

This parameter is specified only in asynchronous system calls. 
It contains a token designating the mailbox that is to receive 
the result of the call. This information is provided by tasks 
to synchronize parallel operations. The I/O result segment 
returned to this mailbox is described in Appendix C. 

NOTE 

Result information should be deleted once it is no longer 
needed. Otherwise, it will consume available memory. 



OBSTETRICS 



GYNECOLOGY 



:OBS: 



POSTPARTUM 




:LABOR: 



:GYN: 



IN-PATIENT 



OUT-PATIENT 





:HOSP: :HOME: 

Figure 8-2. Sample Directory Tree (Synchronous Call) 
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SPECIAL OBJECTS AND DATA TYPES 

Each system call explains in detail the expected contents of 
its input parameters. These explanations frequently refer to 
the following PL/M data types and RMX/86 special objects. 

BYTE is an 8-bit unsigned binary number ranging from to 255 
and occupying one byte of memory. 

BOOLEAN is a single-BYTE quantity taking the value TRUE (0FFH) 
or FALSE (00H). 

STRING is a sequence of BYTES, the first of which contains the 
number of BYTES in the sequence (not including the first, or 
length, BYTE). A length of zero specifies a null string. 

WORD is a 16-bit unsigned binary number ranging from to 65535 
and occupying two contiguous BYTES of memory (with the loworder 
BYTE first). 

TOKEN is two contiguous BYTES of memory whose contents are 
specified to obtain an RMX/86 object. 

CONNECTION is a TOKEN for a connection object. 

USER is a TOKEN for a user object. 

POINTER is two WORDS of memory containing an OFFSET WORD and a 
segment TOKEN (base), respectively. 

CONDITION CODES 

The I/O system issues a condition code when a system call is 

invoked. If the call executes normally, the I/O system returns 

the code "E$OK." If an error is encountered, an exceptional 
condition occurs. 

When an exceptional condition occurs, the system issues a 
condition code describing the error, then either returns to the 
calling task or passes control to an exception handler. See the 
RMX/86 Nucleus, Terminal Handler and Debugger Reference Manual 
for a detailed description of exception handling. 

Exceptional conditions can be programming errors, meaning they 
can be corrected by receding, or environmental conditions, 
meaning they can occur even after a program has been completely 
debugged. These exceptional conditions are detected syn- 
chronously with system call invocation (for example, detection 
of an invalid parameter). The condition code is returned to the 
location addressed by the "excepSptr" field of the external 
procedure declaration associated with each system call (see 
Appendix B) . 
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At the asynchronous level, exceptional 
detected asynchronously (for example, 
cannot know if a file exists before 
Condition codes describing asynchronous 
are returned in the "status" field of 
(Appendix C). The I/O result segment is 



conditions can also be 
when the I/O system 

trying to attach it), 
exceptional conditions 

the I/O result segment 

then sent to the mail- 



box designated 
calls . 



by the "resp$mbox" parameter in asynchronous 



Each of the system call descriptions in this chapter lists the 
condition codes liable to result from invoking that call. An 
explanation of each exceptional-condition code and the probable 
reasons for its occurrence can be found in Appendix D. Asyn- 
chronous exceptional-condition codes are explained in Appendix 
C. 

SYSTEM CALLS 



The following pages provide a detailed description of each I/O 
system call, listed alphabetically. Appendix A provides a 
summary of these calls ,' grouped by function and correlated to 
the file types to which they apply. That summary also acts as a 
cross-reference to the following detailed descriptions. 



INVOKING I/O SYSTEM CALLS IN PL/M 

A$ATTACH$FILE 

ASYNCHRONOUS ATTACH$FILE SYSTEM CALL 

The A$ATTACH$FILE system call creates a connection to an exist- 
ing file. Once the connection is established, it remains in 
effect until it is detached (see A$DELETE$CONNECTION) , or until 
the creating job is deleted (see EXIT$IO$JOB) . Once attached, 
the file may be opened, closed, read, written, etc., as many 
times as desired. 

NOTE 

Any task invoking this call must have a 
priority of 32 or greater. 



CALL RQ$A$ATTACH$FILE(user, prefix, subpath, 

resp$mbox, excep$ptr); 



INPUT PARAMETERS 



user 



is a token for the user object to be in- 
spected in any access checking that takes 
place. A zero specifies the default user for 
the job. This parameter is ignored for 
physical and stream files. 



prefix 



subpath 



resp$mbox 



is a token for the connection object to be 
used as the path prefix. Normally, this will 
be a connection to an existing file (fol- 
lowed by a null subpath). A zero specifies 
the default prefix for the job. 

is a pointer to the string containing the 
subpath of the file to be attached. A null 
string indicates that the new connection is 
the file designated by the prefix: the new 
connection will not be open, regardless of 
the open state of the prefix. 

is a token for the mailbox that receives the 
result of the call. 



excepSptr 



is a pointer to the location that receives 
the condition code resulting from this call. 



RESULT SEGMENT 



result 



is a token for the new connection if the 
call succeeded; an I/O result segment 
(Appendix C) is returned otherwise. 
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A$ATTACH$FILE (continued) 



CONDITION CODES 



E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FNEXIST, E$FTYPE, E$IO, 
E$LIMIT, E$MEM, E$NOPREFIX, E$NOT$CONFIGURED , E$NOUSER, 
E$PARAM, E$TYPE. 
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A$CHANGE$ACCESS 

ASYNCHRONOUS CHANGE$ACCESS SYSTEM CALL 

A$CHANGE$ACCESS system call applies to named files only. It is 
called to change the access rights to a named data or directory 
file. Depending on the contents of the "id" and "access" 
parameters specified in the system call, users may be added to 
or deleted from the files's ID-access list, or the access 
privileges granted to a particular user may be changed. 

NOTE 

Any task invoking this call must have 
a priority of 32 or greater. 



CALL RQ$A$CHANGE$ACCESS(user, 

access 



prefix, subpath, id, 
resp$mbox, excepSptr); 



INPUT PARAMETERS 



user 



prefix 



subpath 



is a token for the user object to be in- 
spected in access checking. A value of zero 
specifies the default user for the job. 

is a token for the connection to be used as 
the path prefix. Typically, this would be a 
connection to the file whose access is being 
changed (followed by a null subpath). A zero 
specifies the default prefix for the job. 

is a pointer to the string giving the sub- 
path from the prefix to the file whose 
access is to be changed. A null string 
indicates the connection is to the file 
designated by the prefix. In this case, the 
user parameter is not used, since access 
rights are already frozen into the 
connection. 



Id 


IS a 




whose 




does 




list , 




total 


access 


is a 



word giving the ID number of the user 
access is to be changed. If this ID 

not already exist in the ID-access 
it is added. This list may contain a 

of three ID-access pairs. 



byte mask giving the new access rights 
for the ID. If a bit is set to one, the 
corresponding access is granted.- For a named 
data file, the possible bit settings are: 
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A$CHANGE$ACCESS (continued) 



INPUT PARAMETER 
access (continued) 



resp$mbox 



excep$ptr 

RESULT SEGMENT 
result 



Bit 



1 

2 

3 
A-7 



Meaning 

Delete 

Read 

Append 

Update 

Reserved 



For a named directory file, the possible bit 
settings are: 



Bit 



1 

2 

3 
A-7 



Meaning 
Delete 
Display 
Add Entry 
Change Entry 
Reserved 



If zero is specified for the 
parameter (that is, no access), 
specified in the ID parameter is 
from the file's ID-access list. 



access 
the ID 
deleted 



is a token for the mailbox that receives an 
I/O result segment indicating completion of 
the access change. A zero value for this 
parameter indicates that no response is 
wanted. 

is a pointer to the location that receives 
the condition code resulting from this call. 



is an I/O result segment indicating comple- 
tion of the access change. See Appendix C. 



FILE ACCESS REQUIREMENTS 

The caller must be the owner of the file or must have change- 
entry access to the file's parent directory. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FLUSHING, 
E$FNEXIST, E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$TYPE. 
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A$CLOSE 



ASYNCHRONOUS CLOSE SYSTEM CALL 

The A$CLOSE system call closes an open file connection. It is 
called between uses of a file. A file connection must also be 
closed if the user wishes to change the open mode or shared 
status of the connection. 



CALL RQ$A$CLOSE(connection , resp$mbox, excep$ptr); 



INPUT PARAMETERS 
connection 

resp$mbox 



is a token for a file connection to be 
closed. 

is a token for a mailbox that receives an 
I/O result segment indicating completion of 
the operation. A zero value for* this 
parameter indicates that no response is 
wanted . 

is a pointer to the location that receives 
the condition code resulting from this call. 



is an I/O result segment (Appendix C) indi 
eating completion of the close operation. 



excep$ptr 

RESULT SEGMENT 
result 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FLUSHING, E$LIMIT, 
E$MEM, E$NOT$CONFIGURED, E$TYPE. 
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A$CREATE$DIRECTORY 

ASYNCHRONOUS CREATE$DIRECTORY SYSTEM CALL 

The A$CREATE$DIRECTORY system call is applicable to named 
directory files only. When called, it creates a new directory 
file and returns a token for the new file connection. This 
system call cannot be used to create a connection to an exist- 
ing directory. 

NOTE 

Any task invoking this call must have 
a priority of 32 or greater. 



CALL RQ$A$CREATE$DIRECTORY(user , prefix, subpath, access, 

respSmbox, excep$ptr); 



INPUT PARAMETERS 



user 



prefix 



subpath 



access 



is a token for the user object of the new 
directory's owner. It is also inspected to 
make sure the caller has proper access to 
the new directory's parent. If zero is 
specified, the default user for the job is 
assumed . 

is a token for the connection to be used as 
the path prefix. A zero specifies the de- 
fault prefix for the job. 

is a pointer to the string giving the sub- 
path of the directory to be created. The 
subpath string must not be null, and must 
point to a location in the directory tree 
where a file has not yet been defined. 

is a byte mask giving the owner's initial 
access rights to the directory. For each bit 
in the mask, a one grants access and a zero 
denies it. The possible bit settings are: 



Bit 



1 

2 

3 
4-7 



Meaning 
Delete 
Display 
Add Entry 
Change Entry 
Reserved 



resp$mbox 
excep$ptr 



is a token for the mailbox that receives the 
result of this call. 

is a pointer to the location that receives 
the condition code resulting from this call. 



8-13 



INVOKING I/O SYSTEM CALLS IN PL/M 
A$CREATE$DIRECTORY (continued) 



RESULT SEGMENT 
result 



is a token for the directory file connection 
if the call succeeded; otherwise, an I/O 
result segment (Appendix C) is returned. 



FILE ACCESS REQUIREMENT 

The caller must have add-entry access to the parent of the new 
directory. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FEXIST, 
E$FNEXIST, E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$SPACE, E$TYPE. 
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ASYNCHRONOUS CREATE$FILE SYSTEM CALL 



A$CREATE$FILE 



The A$CREATE$FILE system call creates a physical, stream, or 
named data file and returns a token for the new file con- 
nection. If a named file designated by the prefix and subpath 
parameters already exists, one of the following situations 
occurs : 

If the "must$create" parameter is TRUE, an error con- 
dition code (E$FEXIST) is returned. 

If the "must$create" parameter is FALSE and the path 
designates a data file, a new connection to that file is 
returned (that is, A$CREATE$FILE 
A$ATTACH$FILE) . In this case, the file is 
zero length after being attached and any 
file is lost. If the "size" parameter is 
requested space is subsequently allocated. 



acts like 

truncated to 

data in the 

nonzero, the 



If the "must$create" parameter is FALSE and the path 

designates a device' or directory, an unamed file is 

created on the corresponding device. This file is 

deleted automatically when the last connection to it is 
deleted . 



Many of the parameters 
not apply to physical 
parameter is ignored. 



specified in the A$CREATE$FILE call do 
and stream files. In these cases, the 



NOTE 

Any task invoking this call must have 
a priority of 32 or greater. 



CALL 


RQ$A$CREATE$FILE(user, prefix, subpath, access, 

granularity, high$size low$size, 
must$create, resp$mbox, excepSptr); 



INPUT PARAMETERS 



user 



prefix 



applies to named files only and is a token 
for the user object of the file's owner. It 
also furnishes the user ID for any access 
checking that might occur. A zero specifies 
the default user for the job. This parameter 
is ignored for physical and stream files. 

is a token for a device or file connection. 
By implication, this parameter indicates the 
type of file (physical, stream, named) being 
created. For a stream file, the prefix is a 
device connection. In the case of a named 
file, the prefix acts as the starting point 
in a directory tree scan. A zero specifies 
the default prefix for the job. 
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A$CREATE$FILE (continued) 



INPUT PARAMETERS (continued) 



subpath 



access 



granularity 



high$size 
lowSsize 



must$create 



applies to named files only and is a pointer 
to the string giving the subpath for the 
file being created. 

applies to named files only and is a byte 
mask giving the owner's initial access 
rights to the new file. For each bit, a one 
grants access and a zero denies it. The 
possible bit settings are: 



Bit 



1 

2 

3 
4-7 



Meaning 

Delete 

Read 

Append 

Update 

Reserved 



applies to named files only and is a word 
giving the granularity of the file being 
created. This is the size (in bytes) of each 
logical block to be allocated to the file. 
The value specified in this parameter is 
rounded up to a multiple of the volume 
granularity. Note that a contiguous file can 
be extended into a noncontiguous file by 
writing past the contiguous extents. 

The granularity parameter can have the 
following values: 

Same as volume granularity 

0FFFFH Contiguous 

other Number of bytes/allocation 

When a contiguous file is extended, space is 
allocated in volume-granularity units. If 
"other" is specified, a multiple of 1024 
bytes is recommended. 

This parameter is isgnored for physical and 
stream files 

is applicable to stream and named files only 
and is a word pair giving the number of 
bytes initially reserved for the file. 

is applicable to named files only and is a 
boolean whose TRUE or FALSE setting deter- 
mines the handling of input paths desig- 
nating an existing file. 
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A$CREATE$FILE (continued) 



INPUT PARAMETERS (continued) 



resp$mbox 

excepSptr 

RESULT SEGMENT 
result 



is a token for the mailbox that receives the 
result of this call. 

is a pointer to the location that receives 
the condition code resulting from this call. 



is the token for a new file connection if 
the call succeeded; otherwise, an I/O result 
segment (Appendix C) is returned. 



FILE ACCESS REQUIREMENT 

The caller must have add-entry access to the parent directory 
of the new named file. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FEXIST, 
E$FNEXIST,E$FTYPE, E$IO, E$LIMIT, E$MEM, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$SPACE , E$TYPE . 
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A$DELETE$CONNECTION 
ASYNCHRONOUS DELETE$CONNECTION SYSTEM CALL 

The A$DELETE$CONNECTION system call severs the file connection 
established by A$CREATE$FILE , A$CREATE$DIRECTORY , or 
A$ATTACH$FILE. It frees the file connection object, and also 
deletes the associated file if the file is already marked for 
deletion (by a previous A$DELETE$FILE call), and if the speci- 
fied connection is the last remaining connection to the file. 
If a connection is open when A$DELETE$CONNECTION is called, it 
is closed before being severed. 

NOTE 



Connections should be deleted when no longer 
needed to avoid exceeding a job's object limit. 



CALL RQ$A$DELETE$CONN£CTION(connection, resp$mbox, excep$ptr) ; 



INPUT PARAMETERS 
connection 



is a token for the file connection to be 
severed. 



resp$mbox 



excep$ptr 



is a token for the mailbox that receives an 

I/O result segment indicating completion of 

the operation. A zero indicates that no 
response is wanted. 

is a pointer to the location that receives 
the condition code resulting from this call. 



RESULT SEGMENT 
result 



is an I/O result segment (Appendix C) indi- 
cating the connection has been deleted. 



CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$IO, E$LIMIT, E$MEM, 
E$NOT$CONFIGURED, E$TYPE. 
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A$DELETE$FILE 



ASYNCHRONOUS DELETE$FILE SYSTEM CALL 



The A$DELETE$FILE system call applies to stream and named files 
only. When called, it marks the designated file for deletion. 
The file is not actually deleted, however, until all con- 
nections to the file have been severed (by A$DELETE$CONNECTION 
calls). Directory files cannot be deleted unless they are empty. 

Some of the parameters specified above do not apply to stream 
files . 

NOTES 

The "prefix/subpath" parameters must specify an 
existing connection. 

Any task invoking this call using a path that 

is not null must have a priority of 32 or greater. 

If the path is null, 

the task can have any priority. 



CALL RQ$A$DELETE$FILE(user, prefix, subpath, resp$mbox); 



INPUT PARAMETERS 



user 



prefix 



subpath 



resp$mbox 



excepSptr 



applies to named files only and is a token 
for the user object to be inspected in 
access checking. A zero specifies the 
default user for the job. 

is a token for a connection. In the case of 

a named file, this prefix acts as the 

starting point in a directory tree scan. A 

zero specifies the default prefix for the 
job. 

applies to named files only and is a pointer 
to a string giving the subpath for the file 
being deleted. A null string indicates that 
the prefix itself designates the desired 
file. In this instance, the user parameter 
is not used since the caller's access (or 
lack of access) is built into the connection 
addressed by the prefix parameter. 

is a token for a mailbox that receives an 
I/O result segment indicating the file is 
marked for deletion. A zero specification 
for this parameter indicates that no res- 
ponse is wanted. 

is a pointer to the location that receives 
the condition code resulting from this call. 
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A$DELETE$FILE (continued) 



RESULT SEGMENT 



result 



is an I/O result segment (Appendix C) indi- 
cating completion of this operation. The 
result is returned when the file is marked 
for deletion, rather than when the file is 
actually deleted. 

FILE ACCESS REQUIREMENT 

The caller must have delete access to the file. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FNEXIST, 
E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$TYPE. 
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A$GET$CONNECTION$STATUS 

ASYNCHRONOUS GET$CONNECTION$STATUS SYSTEM CALL 

The A$GET$CONNECTION$STATUS system call returns information 
about a designated file connection. 



CALL RQ$A$GET$CONNECTION$STATUS(connection, resp$mbox 

excepSptr) ; 



INPUT PARAMETERS 
connection 

respSmbox 

excep$ptr 

RETURN STRUCTURE 
status 



is a token for the file connection whose 
status is desired. 

is a token for the mailbox that receives the 
connection-status information. 

is a pointer to the location that receives 
the condition code resulting from this call. 



is the connection-status information 
returned to the specified mailbox. This 
information is structured as follows: 



DECLARE 

conn$status 

status 

file$driver 

flags 

open$mode 

open$share 

file$pointer 

access 
); 



STRUCTURE( 
WORD, 
BYTE, 
BYTE, 
BYTE, 
BYTE, 
DWORD, 
BYTE 



These fields are interpreted as follows: 

status is a condition code indicating 
how the status-fetch operation 
completed. If this code is not 
E$OK, the remaining fields must 
be considered invalid. 

file$driver tells the type of file driver 

to which this connection is 

attached. Possible bit values 
are : 

1 Physical files 

2 Stream files 
A Named files 
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A$GET$CONNECTION$STATUS (continued) 



RETURN STRUCTURE (continued) 

flags 



contains two flag bits. If bit 1 
is set to one, this connection is 
active and can be opened. If bit 
2 is set, this connection is a 
device connection. 



open$mode is the mode established when this 
connection was opened. Possible 
values are: 

Connection is closed 

1 Open for reading 

2 Open for writing 

3 Open for reading and 
writing 

open$share is the current shared status 
established when this connection 
was opened. Possible values are: 

Private use only 

1 Share with readers only 

2 Share with writers only 

3 Share with all users 

The open mode and shared state 
are initially set by the A$OPEN 
call . 

file$pointer is the current setting of the 
file pointer for this con- 
nection, by byte location. 



access 



gives the access rights for 
this connection. For each bit 
set to one, the corresponding 
access is granted. Bit values 
are : 



Bit 


Data File 


Directory 





Delete 


Delete 


1 


Read 


Display 


2 


Append 


Add Entry 


3 


Update 


Change Entry 


A-7 


Reserved 


Reserved 



CONDITION CODES 

E$OK, E$BAD$CALL, E$EXIST, 
E$NOT$CONFIGURED, E$TYPE. 



E$FLUSHING, E$LIMIT, E$MEM 
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A$GET$DIRECTORY$ENTRY 

ASYNCHRONOUS GET$DIRECTORY$ENTRY SYSTEM CALL 

The A$GET$DIRECTORY$ENTRY system call applies to named files 
only. When called, it returns the file name associated with a 
specified directory entry. This name is a single subpath com- 
ponent for a file whose parent is the designated directory. 



CALL RQ$A$GET$DIRECTORY$ENTRY(connection, entry$num, 

resp$mbox, excep$ptr); 



INPUT PARAMETERS 
connection 

entry$num 



resp$mbox 

excep$ptr 

RETURN STRUCTURE 
dir$entry 



is a token for the directory file containing 
the desired entry. 

is a word giving the entry number of the 
desired file name. Entries within a 
directory are numbered sequentially starting 
from zero. An E$EMPTY$ENTRY condition code 
may be issued if a file has been deleted and 
the I/O system has not reissued the entry to 
another file. 

is a token for the mailbox that receives the 
file name. 

is a pointer to the location that receives 
the condition code resulting from this call. 



is the directory-entry information returned 
to the mailbox, structured as follows: 



DECLARE 

dir$entry$info 
status 
name (14) 

); 



status 



STRUCTURE( 
WORD, 
BYTE 



name 



indicates how the operation 
completed. E$OK, 

E$EMPTY$ENTRY, and E$DIR$END 
condition codes all indicate 
successful completion. 

is the file name contained in 
the designated entry, null 
padded. This field is valid 
only if status = E$OK. 
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A$GET$DIRECTORY$ENTRY (continued) 

FILE ACCESS REQUIREMENT 

The caller must have display access to the designated directory. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$DIR$END, E$EMPTY$ENTRY , E$EXIST, E$FACCESS, 
E$FLUSHING, E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, 
E$NOT$CONFIGURED, E$TYPE. 
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A$GET$FILE$STATUS 

ASYNCHRONOUS GET$FILE$STATUS SYSTEM CALL 

The A$GET$FILE$STATUS system call returns status and attribute 
information about the designated file. Certain common infor- 
mation is returned regardless of the file driver type (phys- 
ical, stream, or named). Additional information is returned for 
named files. 

Note that this call returns some device-dependent information, 
and its use may cause an application to become device dependent. 



CALL RQ$A$GET$FILE$STATUS(connection, resp$mbox, excep$ptr); 



INPUT PARAMETERS 
connection 

respSmbox 

excep$ptr 

RESULT SEGEMENT 
common$info 



is a token for a connection to the file 
whose status is sought. 

is a token for the mailbox that receives the 
common (and named file) status information. 

is a pointer to the location that receives 
the condition code resulting from this call. 



is the common file-status information 
returned to the designated mailbox. This 
information is structured as follows: 



DECLARE 




commonSinfo STRUCTURE ( 


status 


WORD, 


num$conn 


WORD, 


num$reader 


WORD, 


num$writer 


WORD, 


open$share 


BTYE, 


named$file 


BYTE, 


dev$name (lA) 


BYTE, 


file$drivers 


WORD, 


functs 


WORD, 


devSgran 


WORD, 


dev$size 


DWORD, 


dev$conn 


WORD 



); 

These fields are interpreted as follows 



status 



is a condition code indicating 
how the status-fetch operation 
completed. If this code is not 
E$OK, the remaining fields must 
be considered invalid. 
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A$GET$FILE$STATUS (continued) 



RESULT SEGMENTS (continued) 

num$conn 

num$reader 

num$writer 

open$share 



named$file 



dev$name 



is the number of connections to 
the file. 

is the number of connections 
currently open for reading. 

is the number of connections 
currently open for writing. 

is the current shared status of 
the file. Possible values are: 

Private use only 

1 Share with readers only 

2 Share with writers only 

3 Share with all users 

specifies whether the file is a 
named file and, therefore, 
whether the mailbox will con- 
tain named-file, as well as 
common information. A value of 
0FFH indicates the additional 
information is present. 

is the name of the device where 
this file resides, null padded. 



file$drivers indicates which file drivers 
can be used with the file. If 
bit n is on, then file driver 
n + 1 can be used. Bits are 
numbered right to left starting 
with zero. 



Bit Driver No. 

1 

1 2 

2 3 

3 4 



Driver 

Physical file 
Stream file 
reserved 
Named file 



functs 



describes the functions sup- 
ported by the device where this 
file resides. Each bit set to 
one indicates the corresponding 
function is supported. 
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A$GET$FILE$STATUS (continued) 



RESULT SEGMENTS 
functs (continued) 



named$file$info 



Bit 


Function 





F$READ 


1 


F$WRITE 


2 


F$SEEK 


3 


F$SPECIAL 


4 


F$ATTACH$DEV 


5 


F$DETACH$DEV 


6 


F$OPEN 


7 


F$CLOSE 


8-15 


Reserved 



dev$gran is the device granularity, in 
bytes . 

dev$size is the size of the device, in 
bytes. 

dev$conn is the number of connections to 
the device. 

is the additional information 
returned if the designated file 
is a named file. This 
information is structured as 
follows : 



DECLARE 




named$file$info 


STRUCTURE( 


fdesc$num 


WORD, 


file$type 


BYTE, 


file$gran 


BYTE, 


owner 


WORD, 


create$time 


DWORD, 


access$time 


DWORD, 


mod$time 


DWORD, 


file$size 


DWORD, 


file$blocks 


DWORD, 


vol$name (6) 


BYTE, 


vol$gran 


WORD, 


vol$size 


DWORD, 


id$count 


WORD, 


accessor {*) 


STRUCTURE( 


access 


BYTE, 


id 


WORD) 
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A$GET$FILE$STATUS (continued) 



RESULT SEGMENTS (continued) 

These fields are interpreted as follows: 



fdescSnum 



file$type 



f ile$gran 

owner 

create$time 

access$time 

mod$time 

f ile$size 

file$blocks 

vol$name 
vol$gran 
vol$size 



is the number of the file's 
file descriptor. The file 
descriptor is an I/O system 
data structure containing 
file attribute and status 
data. 

indicates the type of the 
file. A file with type other 
than FT$DATA (data file, 
type = 8) may only be accessed 
from within the I/O system. 

specifies the file gran- 
ularity . 

is the user ID number of the 
file's owner. 

is the time and date when 
the file was created. 

is the time and date when 
the file was last accessed. 

is the time and date when 
the file was last modified. 

is the total size, in bytes, 
of the data in the file. 

is the number of volume 
blocks allocated to this 
file. 

is. the ASCII name for the 
volume containing this file. 

is the volume granularity, 
in bytes. 

is the size of the volume, 
in bytes. 
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A$GET$FILE$STATUS (continued) 



RESULT SEGMENTS (continued) 

id$count 



accessor 



CONDITION CODES 

E$OK, E$BAD$CALL, E$EXIST, 
E$NOT$CONFIGURED, E$TYPE. 



is the number of access/ 
user-ID pairs declared for 
this file. These pairs are 
detailed in the structure 
that follows. 

is a list of up to three 
access/user-ID pairs. 



E$FLUSHING, E$LIMIT, E$MEM, 
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A$GET$PATH$COMPONENT 

ASYNCHRONOUS GET$PATH$COMPONENT SYSTEM CALL 

A$GET$PATH$COMPONENT can be called no matter what type of file 
is supported, but if a connection to a physical or stream file 
is specified, the call simply returns a null string. 

A caller who knows the token for a connection to a file can 
specify the token to this system call and receive the name of 
the file in return. This is the name by which the file is 

^a^tal-oge^d — i^ — its— p-ax exit— done ctjoxy. If the connection is to the 

root directory of a volume (that is, if no parent directory 
exists), a null string is returned. A null string is also 
returned if the file is marked for deletion. 



CALL RQ$A$GET$PATH$COMPONENT(connection, resp$mbox, 

excepSptr) ; 



INPUT PARAMETERS 
connection 

respSmbox 

excep$ptr 

RESULT SEGMENT 
f ile$name 



CONDITION CODES 

E$OK, E$BAD$CALL, 
E$NOT$CONFIGURED, 



is a token for the file connection whose 
name is sought. 

is a token for the mailbox that receives the 
result segment containing the file name 
associated with the designated connection. 

is a pointer to the location that receives 
the condition code resulting from this call. 



is a result segment giving the name of the 
file. This segment should be structured as 
follows; 

DECLARE FILE$NAME 

file$name STRUCTURE( 
STATUS WORD, 

name BYTE 

); 

These fields are interpreted as follows: 

status is a condition code indicating 
how the operation completed. 

name is an ASCII string giving the 
desired file name. This name is 
the same as the last item in 
the subpath string specified 
when the file was created or 
renamed. 



E$EXIST, E$FLUSHING, E$IO, E$LIMIT, E$MEM, 

E$TYPE. 
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A$OPEN 



ASYNCHRONOUS OPEN SYSTEM CALL 



The A$OPEN system call opens a connection for I/O operations. 
The connection must be opened before such operations as reading 
and writing can be performed. 

A$OPEN checks the current shared status of the connected file, 
and returns an error message if the requested mode is incon- 
sistent with the sharing permitted. Open reouests are not 
queued. 

A$OPEN also initializes the file pointer to byte position zero. 
Subsequent I/O system calls (A$SEEK, A$READ, and A$WRITE) will 
move this pointer. 

If the file is attached by multiple connections, the file might 
be open for reading by some connections and open for writing by 
others at the same time. Any modification of the file by a 
writer will be seen by the reader, if a reader subsequently 
reads the modified part of the file. 

Note also that access to a file may be denied due to 
mode/shared-state incompatibility. No deadlock occurs, however, 
since open calls are not queued. The system does not notify 
callers when the shared status of the connection changes. If 
such notification is important, users of the file should 
arrange a proper protocol. 



CALL RQ$A$OPEN(connection , mode, share, resp$mbox, excepSptr); 



INPUT PARAMETERS 



connection 
mode 



is a token for the connection to be opened. 

is a byte giving the mode desired for the 
open connection. Possible values are: 



Open for reading 
Open for writing 
Open for both reading and writing 



share 



is a byte specifying the kind of sharing 
desired for this connection. Possible values 
are : 



Private use only 
Share with readers only 
Share with writers only 
Share with all users 
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A$OPEN (continued) 

INPUT PARAMETERS (continued) 



resp$mbox 



is a token for the mailbox that receives the 
I/O result segment indicating completion of 
this operation. A zero value for this 
parameter indicates that no response is 
wanted. 



excep$ptr 

RESULT SEGMENT 
result 



is a pointer to the location that receives 
the condition code resulting from this call. 



is an I/O result segment (Appendix C) indi- 
cating that the open operation has been 
completed. 



FILE ACCESS REQUIREMENT 

The mode parameter must be compatible with the current shared 
state of the connected file. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FLUSHING, 
E$LIMIT, E$MEM, E$NOT$CONFIGURED , E$PARAM, E$SHARE, E$TYPE. 
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A$READ 



ASYNCHRONOUS READ SYSTEM CALL 



The A$READ system call initiates a read operation from an open 
connection. The connection is read as a string of bytes, 
starting at the current file pointer, and any number of bytes 
can be requested. Some efficiency may be gained by starting 
reads on device block boundaries. After the read operation is 
finished, the file pointer points just past the last byte read. 

The buffer specified by the "buff$ptr" parameter must be in a 
segment allocated by the free-space manager of the RMX/86 
nucleus executive (that is, the segment must be allocated 
dynamically ) . 



CALL RQ$A$READ(connection , buff$ptr, count, resp$mbox, 
excepSptr ) ; 



INPUT PARAMETERS 



connection 



count 
resp$mbox 

excep$ptr 

RESULT SEGMENT 
result 



is a token for the open file connection to 
be read. 



buff$ptr is a pointer to the buffer that receives the 
data read. 



is a word giving the number of bytes to be 
read . 

is a token for the mailbox that receives the 
I/O result segment after the read is com- 
plete. A zero value for this parameter 
indicates that no response is wanted. 

is a pointer to the location that receives 
the condition code resulting from this call. 



is an I/O result segment (Appendix C) indi- 
cating completion of the read operation. It 
also contains the actual number of bytes 
read. 

If a read operation is requested with the 
file pointer set at or beyond the end of the 
file, an actual-bytes-read count of zero is 
returned in the I/O result segment. 

If all the connections to a stream file are 
requesting read operations, an actual-bytes- 
read count of zero is returned in the I/O 
result segment. 
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A$READ (continued) 



FILE ACCESS REQUIREMENT 

The mode of the open connection must permit reading (see 
A$OPEN). 

CONDITION CODES 



-E$eK-, t$BA£)^^AbL^ E$£-6^M^E-X-T-, E4EX^tST-^ E$f^tySl4XW£-, E$l-0-,- 

E$LIMIT, E$MEM, E$NOT$CONFIGURED , E$TYPE. 
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A$RENAME$FILE 



ASYNCHRONOUS RENAME$FILE SYSTEM CALL 



The A$RENAME$FILE system call applies to named files only, 
is called to change the name of a file. 



It 



A renamed data file can be recataloged in a different parent 
directory, so long as that directory is on the same volume as 
the file's original parent. Renamed directory files must keep 
the same parent, however. 



CALL RQ$A$RENAME$FILE(connection, user, prefix, subpath, 

resp$mbox, excepSptr); 



INPUT PARAMETERS 



connection 



user 



prefix 



subpath 



resp$mbox 

excepSptr 

RESULT SEGMENT 
result 



is a token for a connection to the file 
being renamed. This connection and all other 
connections to the file will remain in 
effect after the file is renamed. 

is a token for the user object to be in- 
spected in access checking. A zero specifies 
the default user for the job. 

is a token for the connection to be used as 
the starting point in a path scan. A zero 
specifies the default prefix for the job. 

is a pointer to the string giving the new 
subpath for the file. Prefix and subpath 
must lead to a nonexistent file. The string 
pointed to by the subpath parameter cannot 
be a null string. 

For a data file, prefix and subpath may 
specify a different directory from the 
original parent, but it must be on the same 
volume. A directory file can only be renamed 
within its parent directory, however. 

is a token for the mailbox that receives an 
I/O result segment indicating completion of 
the rename. A zero value for this parameter 
indicates that no response is wanted. 

is a pointer to the location that receives 
the condition code resulting from this call. 



is an I/O result segment (Appendix C) indi- 
cating that the rename operation is finished. 
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A$RENAME$FILE (continued) 



FILE ACCESS REQUIREMENTS 

The caller must have delete access to the original file and 
must have add-entry access to the file's parent directory. 

CONDITION CODES 

-E$CU4^ E^BAD^A^.^.^ E$^ON-TE^X^^ E^O^ST-, &$^AC&&SS-, ES^E^XXST^^ 

E$FLUSHING, E$FNEXIST, E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, 
E$NOPREFIX, E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$SUPPORT, 
E$TYPE. 
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A$SEEK 



The A$SEEK system call applies to physical and named files 
only. This call moves the file pointer for an open connection, 
thus allowing file contents to be accessed randomly. The file 
pointer can be moved to any byte position in the file. 



CALL RQ$A$SEEK( connection , mode, hi$ptr$move, low$ptr$move , 

resp$mbox, excepSptr); 



INPUT PARAMETERS 
connection 

mode 



hi$ptr$move 
low$ptr$move 



resp$mbox 

excepSptr 

RESULT SEGMENT 
result 

CONDITION CODES 

E$OK, E$BAD$CALL, 
E$LIMIT, E$MEM 



is a token for the open file connection 
whose file pointer is to be moved. 

is a byte describing the movement of the 
file pointer. Possible values are: 

1 Move pointer back by "ptr$move" 
amount. If this action moves the 
pointer past the beginning of the 
file, the pointer is set to zero. 

2 Set the pointer to the location 
specified by "ptr$move." 

3 Move the file pointer forward by 
"ptr$move" amount. 

4 Move the pointer to the end of the 
file, minus the "ptr$move" 
specified . 

is a word pair giving the number of bytes 
involved in the seek. The interpretation of 
"ptr$move" depends on the mode setting, as 
explained above. 

is a token for the mailbox that receives an 
I/O result segment when the seek is 
completed. A zero value for this parameter 
indicates that no response is wanted. 

is a pointer to the location that receives 
the condition code resulting from this call. 



is an I/O result segment (Appendix C) indi- 
cating that the seek operation has been 
completed . 



E$CONTEXT, E$EXIST, E$FLUSHING, E$IFDR, E$IO, 
, E$NOT$CONFIGURED, E$PARAM, E$TYPE. 
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ASSPECIAL 



ASYNCHRONOUS SPECIAL SYSTEM CALL 

The A$SPECIAL system call applies to physical files only. It 
lets the caller perform special device-level functions. 

The special function to be done can be specified using either 
of two methods. If the function requires little supporting 
information (such as a function to rewind a magnetic tape), its 
cod^— c^fl— b-e— sp^aai Xijad dlTBJ2tly as the "spec$func" p arameter in 



the system call. 

Where additional information is needed, the user must create an 
I/O parameter block as described below. The special function is 
specified indirectly, as a field in this parameter block. The 
block is then addressed by the "ioparm$ptr" in the system call. 

If only the "spec$func" parameter is used to specify the 
special function, the "ioparm$ptr" parameter is specified as 
zero . 



CALL RQ$A$SPECIAL(connection , spec$func, ioparm$ptr, 

resp$mbox, excepSptr); 



INPUT PARAMETERS 



connection 



spec$func 



ioparm$ptr 



resp$mbox 



excepSptr 



is a token for a connection to the file 
where the special function is to be 
performed. 

is a word (code) that allows the user to 
pass a special function to a file driver 
without being required to set up a parameter 
block . 

is a pointer to a parameter block. The 
contents of the parameter block depends upon 
the requirements of the file driver being 
used to implement the special function. If 
the file driver requires no parameters for 
the function being requested, then 
ioparm$ptr can be zero. If the function does 
require parameters, you must build the 
parameter block to satisfy the requirements 
of the specific file driver. 

is a token for the mailbox that receives an 
I/O result segment indicating that the 
special function has been completed. A zero 
value in this parameter indicates that no 
result is wanted. 

is a pointer to the location that receives 
the condition code resulting from this call. 
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A$SPECIAL (continued) 



RESULT SEGMENT 
result 

CONDITION CODES 



is an I/O result segment (Appendix C) indi- 
cating that the special function has been 
completed . 



E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FLUSHING, E$IDDR, 
E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOT$CONFIGURED , E$TYPE. 
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A$TRUNCATE 



ASYNCHRONOUS TRUNCATE SYSTEM CALL 

The A$TRUNCATE system call applies to named files only. This 
call truncates a file at the current setting of the file 
pointer, freeing all allocated space beyond the pointer. A$SEEK 
can be called to position the pointer before A$TRUNCATE is 
called. If the file pointer is at or beyond the end-of-file, no 
operation is performed. 



Truncation is performed immediately, rather than waiting until 
connections to the file are deleted. 



CALL RQ$A$TRUNCATE(connection, resp$mbox, excep$ptr); 



INPUT PARAMETERS 
connection 

resp$mbox 



excep$ptr 

RESULT SEGMENT 
result 



is a token for an open connection to the 
file being truncated. 

is a token for the mailbox that receives an 
I/O result segment indicating the truncation 
has been completed. A zero value for this 
parameter indicates that no response is 
wanted . 

is a pointer to the location that receives 
the condition code resulting from this call. 



is an I/O result segment (Appendix C) indi- 
cating completion of this operation. 



FILE ACCESS REQUIREMENT 

The designated file connection must be open for writing. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FLUSHING, 
E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOT$CONFIGURED , E$TYPE. 
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A$WRITE 



ASYNCHRONOUS WRITE SYSTEM CALL 



The A$WRITE call writes data from the caller's buffer to a 
connected file. The data is written starting at the current 
file pointer. After the write, the file pointer is positioned 
just after the last byte written. Some efficiency may be gained 
by starting writes on device block boundaries. 

NOTE 

The buffer supplying the data to be written 
should not be modified until the write request 
has been acknowledged at the response mailbox. 

This buffer must reside in a segment 

allocated by the RMX/86 nucleus' free-space 

manager (that is, the segment must be 

allocated dynamically). 



CALL RQ$A$WRITE(connection , buff$ptr, count, resp$mbox, 

excepSptr ) ; 



INPUT PARAMETERS 
connection 

buffSptr 

count 

resp$mbox 

excep$ptr 

RESULT SEGMENT 
result 



is a token for the open connection to be 
written. 

is a pointer to the buffer that supplies the 
data to be written. 

is a word giving the number of bytes to be 
written. 

is a token for the mailbox that receives the 
I/O result segment indicating the write is 
complete. A zero value in this parameter 
indicates that no response is wanted. 

is a pointer to the location that receives 
the condition code resulting from this call. 



is an I/O result segment (Appendix C) indi- 
cating that the write operation has been 
completed. It also contains the actual 
number of bytes written. 

If all the connections to a stream file are 
requesting write operations, an actual-bytes 
written count of zero is returned. 
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A$WRITE (continued) 



FILE ACCESS REQUIREMENTS 

The designated file connection must be open for writing, and 
the caller must have append or update access to the connection. 

CONDITION CODES 



-E^OK-, &$^&AD-$&Attr^ E-$^ON-T^^T^ E4E-Xl-^"h E-$FtU5 H-IM^^ Er$^^ 

E$LIMIT, E$MEM, E$NOT$CONFIGURED , E$SPACE, E$SUPPORT, E$TYPE . 
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CREATE I/O JOB SYSTEM CALL 



CREATE$IO$JOB 



The CREATE$IO$JOB system call creates a job and one task within 
the job. In doing so, it invokes the nucleus' CREATE$JOB call, 
requiring the caller to define the parameters needed by this 
call. The CREATE$IO$JOB call also includes several parameters 
useful for I/O processing and creates a mailbox for commun- 
ication between the new job and its parent. 



job = RQ$CREATE$IO$JOB( job$data$ptr, prefix$ptr, 

log$nam$ptr, task$flags, 
task$prior, task$start$addr , 
data$token, stack$ptr, 
stack$size, excep$ptr); 



job$data$ptr 



pref ixSptr 



log$nam$ptr 



task$f lags 



taskSprior 



is a pointer to a job parameter structure 
as defined below. 



is a pointer to a string that gives the 
default prefix for the job (specified as a 
logical name). A null string or zero 
pointer specifies that the calling job's 
default prefix is to be used. 

is a pointer to a contiguous set of 
string/ token pairs, each giving a logical 
name to be inherited by the new job from 
its creator. A zero token associates its 
corresponding string with the parent job's 
token for the same string. The list is 
ended by a null string. A zero indicates 
that no logical names are to be , inherited 
by the new job. 

is a word containing information about the 
initial task in the new job. 

is a byte specifying the priority of the 
new task. This priority must be lower 
(higher numerically) or equal to the 
parent job's maximum priority. A zero 
specifies that the task has the highest 
priority allowed by its job. 

task$start$addr is a pointer to the entry point of the 

task to be created within the new job. 



data$token 



is a token to which the initial task's DS 
and ES registers will be initialized. If 
zero, DS and ES are initialized to the 
value of the new job's CS register. 
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CREATE$IO$JOB (continued) 

INPUT PARAMETERS (continued) 



stack$ptr 



is a pointer to the stack of the task 
being created within the new job. If the 
base of this address is zero, the system 
allocates a stack segment equal in size to 
the "stack$size" parameter described below. 



stack$size 
excepSptr 



is a word containing the size of the stack 
for the new job's initial task. 

is a pointer to the location that receives 
the condition code resulting from this 
call . 



The job$param$ptr parameter points to a 
rameter structure declared as follows: 



predefined job pa- 



DECLARE 






job$data 


STRUCTURE( 


dir$size 




WORD, 


param$obj 




TOKEN, 


pool$min 




WORD, 


pool$max 




WORD, 


max$objects 




WORD, 


max$tasks 




WORD, 


max$prior 




BYTE, 


excep$hdler$o 


ffset 


WORD, 


excep$hdler$b 


ase 


WORD, 


excep$mode 




BYTE, 


job$f lags 




WORD, 


global$job 




TOKEN, 


user 




TOKEN, 


msg$mbox 




TOKEN 



where: 

dir$size 

param$obj 
pool$min 



contains the maximum number of entries 
allowed in the new job's object directory. 

designates the new job's parameter object. 
A zero specifies that the job does not 
have a parameter object. 



contains the 
pages, of the 
This 
size . 



minimum 
created 
figure is also 



size, in 16-byte 

job's memory pool. 

the pool's initial 
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CREATE$IO$JOB (continued) 



INPUT PARAMETERS 
where: (continued) 

pool$max 



max$objects 



max$tasks 



max$prior 



excep$hdler$offset 
excep$hdler$base 



excep$mode 



job$flags 



global$job 



contains the maximum size, in 16-byte 
pages, of the created job's memory 
pool. This figure must be greater than 
or equal pool$min. 

contains the maximum number of objects 
that the new job can contain simultan- 
eously. 0FFFFH specifies an unlimited 
number . 

contains the maximum number of tasks 

that can exist simultaneously within 

the new job. 0FFFFH specifies an 

unlimited number. 

is the maximum priority of any task in 
the new job from 1 (high) to 255 (low). 
A zero specifies that the highest 
priority is the same as that of the 
parent job's tasks. 

form a pointer to the exception handler 
for the new job. A zero specifies the 
system default exception handler to be 
used . 

specifies if and when control should be 
passed to the job's exception handler. 
Possible values are: 



No exceptions recognized. 
Recognize programming errors 
only . 

Recognize environmental condi- 
tions only. 
Recognize all exceptions. 



contains job information needed by the 
RMX/86 nucleus. If any tasks in the job 
use the 8087 component, the low-order 
bit should be set to one. 

specifies the job whose object direc- 
tory is to be used as the global 
logical-name directory for the job 
being created. A zero specifies that 
the caller's global job is to be used. 
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CREATE$IO$JOB (continued) 



where (continued) 
user 

msg$mbox 



RETURN VALUE 
job 

CONDITION CODES 



specifies the default user object for 
the new job. A zero specifies that the 
calling job's default is to be used. 

is a token for the mailbox through 
-wh-i-&h — aFvy exi^t — me-s-sa-g^e — ^w-i-l-l — b^ — se-n-t — to 



the parent job. A zero specifies that 
no message is wanted. (See EXIT$IO$JOB) . 



is a token for the new job created by 
this call. 



E$OK, E$LIMIT, E$LOG$NAME$NEXIST, E$MEM, E$NHUSER, E$NOPREFIX, 
E$NOUSER, E$PREFIX$STRING$NEXIST. 
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DELETE$PACKAGE 



DELETE$PACKAGE SYSTEM CALL 



DLLETE$PACKAGE is called to delete a package object previously 
created by the loader, or other source. 



CALL RQ$DELETE$PACKAGE(package, excep$ptr); 



INPUT PARAMETERS 
package 

excep$ptr 



is a token for the package object to be 
deleted . 

is a pointer to the location that receives 
the condition code resulting from this 
call. 
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EXIT$IO$JOB 

EXIT I/O JOB SYSTEM CALL 

The EXIT$IO$JOB system call causes the calling task to be 
deleted. EXIT$IO$JOB performs the following operations: 

© deletes all connections and detaches all logical devices 
attached by the job; 

— c^^€^t8-s— a— sagmefv4 — fe ^ the e^^'^m^e-s s-a^g^e-^ 



© sends the exit message to the mailbox provided by the 
parent job when the exiting job was created.; 

© deletes the calling task. 

The parent of the exiting job can then delete it, if it wishes 
to do so. 

NOTES 

A job whose last task has been deleted will not 
exit automatically. 

No other tasks in a job can be in the ready state 
when a task in the job calls EXIT$IO$JOB. 

Tasks that call EXIT$IO$JOB must use hybrid or 

synchronous file system calls to create 

CKDnnections . Otherwise, a system failure may occur 

when a child job is deleted after being exited. 



CALL RQ$EXIT$IO$JOB(user$excep$code, return$data, 

return$data$len , excep$ptr); 



INPUT PARAMETERS 



user$excep$code 



return$data 



is a word giving a user exception code. If 
this code is zero, the exit is considered 
normal and the exit message contains zeros 
in its return$code and exception$code 
fields. If user$excep$code is nonzero, an 
abnormal exit is assumed and the exit 
message contains a two in its return$code 
field. The exception$code field has the 
same value as user$excep$code . 

is a pointer to the data to be returned to 
the parent job. If the pointer is zero, no 
data is returned. Otherwise, the number of 
bytes specified by the following parameter 
is copied into the return$data field of 
the exit message segment. 
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EXIT$IO$JOB (continued) 



INPUT PARAMETERS (continued) 



return$data$len 
excep$ptr 

RESULT SEGMENT 
exit$msg 



where : 

return$code 



exception$code 



is a word giving the number of bytes to 
be copied into the exit message segment. 

is a pointer to the location that 
receives the condition code resulting 
from this call. 



is the exit message returned to the 

mailbox established by the parent job 

when the exiting job was created. It has 
the following structure: 



DECLARE 
exit$message 
return$code 
exception$code 
job$token 
return$data$len 
return$data(-*) 

); 



STRUCTURE( 
WORD, 
WORD, 
WORD, 
WORD, 
BYTE 



explains the returning condition. 
Possible values for this field are: 

Normal exit; job terminated 
successfully. EXIT$IO$JOB was 
called with user$excep$code 
parameter set to zero. 

1 Job exited due to a system- 
related error. The I/O system 
caused the job to exit. 

2 Job exited due to a user- 
related error. EXIT$IO$JOB was 
called with a nonzero 
user$excep$code paramater. 

gives the exception code, which is 
influenced by the return$code field's 
contents. If return$code is zero, this 
field is zero. If return$code is one 
(system-detected error), this field 
contains an I/O system condition code. 
If return$code is two (user-related 
error), this field has the same code as 
the user$excep$code input parameter. 
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EXIT$IO$JOB (continued) 



RESULT SEGMENT 
where: (continued) 

job$token 



return$data$len 



is a word giving the exited job's token 
relative to the parent job. 

gives the length (in bytes) of the 
Fetu^rn^d-a-ta — 



-pirov-i^&d- 



-w-i-'th- 



^-he- 



return$data 

CONDITION CODES 

E$OK, E$NOT$CONFIGURED 



EXIT$IO$JOB call. 



is a sequence of bytes containing the 
return$data provided with the 
EXIT$IO$JOB call. 
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GET$DEFAULT$PREFIX 

GET$DEFAULT$PREFIX SYSTEM CALL 

The GET$DEFAULT$PREFIX system call allows the caller to de- 
termine the default prefix for the specified job. 



connection = RQ$GET$DEFAULT$PREFIX( job , excep$ptr); 



INPUT PARAMETERS 
job 

excepSptr 

RETURN VALUE 
connection 



is a token for the job whose default 
prefix is sought. A zero specifies the 
calling job. 

is a pointer to the location that 
receives the condition code resulting 
from this call. 



is a token for the connection object 
which is the default prefix for the 
designated job. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$EXIST, E$NOPREFIX, E$NOT$CONFIGURED , E$TYPE. 
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GET$DEFAULT$USER 

GET$DEFAULT$USER SYSTEM CALL 

The GET$DEFAULT$USER system call allows the calling task to 
determine the default user object associated with the desig- 
nated job. 



user$id = RQ$GET$DEFAULT$USER( job , excep$ptr); 



-mP-W~PA1^AMET-&RS^ 



job 

excepSptr 

RETURN VALUE 
user$id 



is a token for the job whose default 
user object is sought. A zero specifies 
the calling job. 

is a pointer to the location that 
receives the condition code resulting 
from this call. 



is a token for the user object which is 
the default user for the designated job. 



CONDITION CODES 

E$OK, E$BAD$CALL, E$EXIST, E$NOT$CONFIGURED , E$NOUSER, E$TYPE. 
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GET$TIME 



GET$TIME SYSTEM CALL 



The GET$TIME system call returns the date/time value from its 
doubleword counter. 



date$time = RQ$GET$TIME(excep$ptr ) ; 



INPUT PARAMETER 
excepSptr 

RESULT SEGEMENT 
date$time 



is a pointer to the location that receives 
the condition code resulting from this 
call . 



is a doubleword date/time value expressed 
as the number of seconds since midnight, 
January 1, 1978. 



CONDITION CODES 

E$OK, E$BAD$CALL, E$NOT$CONFIGURED . 
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GET$TIME$STRING 

GET$TIME$STRING SYSTEM CALL 

The GET$TIME$STRING system call returns the current date and 
time . 



CALL RQ$GET$TIME$STRING(dt$ptr, excepSptr); 



INPUT PARAMETERS 



dt$ptr 
excepSptr 

RESULT SEGMENT 
date 



time 



is a pointer to the location where the 
date and time values are returned. 

is a pointer to the location that receives 
the condition code resulting from this 
call . 



is a series of ASCII characters giving 
today's date in the form: 



where : 



MM/DD/YY 

"MM" is the month (01 - 12) 

"DO" is the day (01 - 31) 

"YY" is the year (00 - 99) 



is a series of ASCII characters giving the 
current time in the form: 



where 



HH:MM:SS 

"HH" is the hour (00 - 24) 

"MM" is the minute (00 - 39) 

"SS" is the second (00 - 59) 



CONDITION CODES 

E$OK, E$BAD$CALL, E$EXIST, E$NOT$CONFIGURED , E$PARAM, E$TYPE. 
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H$ATTACH$FILE 



HYBRID ATTACH$FILE SYSTEM CALL 



The H$ATTACH$FILE system call creates a connection to an exist- 
ing file. The new connection can also be given a logical name 
and cataloged in the job's logical-name directory. The caller 
is assumed to be the default user for the job. 

NOTE 



Any task invoking this call must have a 
priority of 32 or greater. 



connection = RQ$H$ATTACH$FILE( log$name , path, excep'Sptr) ; 



INPUT PARAMETERS 
log$name 



path 



is a pointer to the string giving the 
logical name under which the new con- 
nection is to be cataloged in the job's 
logical-name directory. A zero in this 
parameter or a null string indicates the 
connection will not have a logical name. 

is a pointer to the string containing the 
prefix and subpath to the file being 
attached . 



excepSptr 



is a pointer to the location that receives 
the condition code resulting from this 
call. 



RETURN VALUE 



connection 



CONDITON CODES 



is a token for the new connection to the 
file designated by the path parameter. 



E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FNEXIST, E$IO, E$LIMIT, 
£$MEM, E$NOPREFIX, E$NOT$CONFIGURED , E$NOUSER, E$PARAM, E$TYPE. 
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H$CHANGE$ACCESS 

HYBRID CHANGE$ACCESS SYSTEM CALL 

The H$CHANGE$ACCESS system call applies to named files only. It 
is called to change the access rights to a named data or direc- 
tory file. The caller is assumed to be the default user. 

NOTE 



GtH^^e-fl4iy-, — a41— u^^rs— t^-v^— acc^s-s^js^all-^i-les-^ 

at the hybrid level. The new access rights 

specified in this call apply to all users, 

including the caller. 



CALL RQ$H$CHANGE$ACCESS(path, mode, name, access, excep$ptr) ; 



INPUT PARAMETERS 
path 

mode 
name 



is a pointer to the string giving the 
prefix and subpath to the file whose 
access rights are to be changed. 

is a byte value, currently ignored. 

is a pointer to the string giving the name 
of the accessor whose rights are being 
added, deleted, or changed. Currently, the 



string must 
users . 



be "WORLD 



which includes all 



access 



is a byte mask giving the new 
rights for the specified accessor 
bit is set to one, 
access is granted. For 



access 

If a 

the corresponding 

a named data file, 



the possible bit settings are: 



Bit 


Meaning 





Delete 


1 


Read 


2 


Append 


3 


Update 


4-7 


Reserved 



For a named directory 
bit settings are: 



file, the possible 



Bit 



1 

2 

3 
A-7 



Meaning 
Delete 
Display 
Add Entry 
Change Entry 
Reserved 
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H$CHANGE$ACCES5 (continued) 



INPUT PARAMETERS (continued) 



excep$ptr 



is a pointer to the location that receives 
the condition code resulting from this 
call . 



FILE ACCESS REQUIREMENTS 

The caller must be the owner of the file or must have change- 
entry access to the file's parent directory. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FLUSHING, 
E$FNEXIST, E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$TYPE . 
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H$CREATE$DIRECTORY 

HYBRID CREATE$DIRECTORY SYSTEM CALL 

The H$CREATE$DIRECTORY system call is applicable to named 
directory files only. When called, it creates a new directory, 
file and returns a token for the connection to the new file. 
The new connection can also be cataloged under a specified 
logical name in the calling job's logical-name directory. 



The— c^ter^rs— assumed— ti3—be^th«—d^"Fatrir^-th&eT — f6-:^-t-he— j-ob^ — Ft^l 
owner access to the directory is assumed; that is, bits 0-3 in 
the access byte mask are all set to one. 



Bit 


Meaning 





Delete 


1 


Display 


2 


Add Entry 


3 


Change Entry 


A-7 


Reserved 



NOTE 



Any task invoking this call 
must have a priority of 32 or greater. 



connection = RQ$H$CREATE$DIRECTORY( log$name , path, excep$ptr); 



INPUT PARAMETERS 
log$name 



path 



excepSptr 



is a pointer to the string giving the 
logical name under which the new con- 
nection is to be cataloged in the calling 
job's logical-name directory. A zero in 
this parameter or a null string specifies 
that the connection is not to be given a 
logical name. 

is a pointer to the string containing the 
prefix and subpath to the directory being 
created. This string cannot be null, and 
the directory name cannot exist already. 

is a pointer to the location that receives 
the condition code resulting from this 
call . 



RETURN VALUE 



connection 



is a token for the connection to the new 
directory file. 



FILE ACCESS REQUIREMENT 

The caller must have add-entry access to the parent of the new 
directory. 
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H$CREATE$DIRECTORY (continued) 



CONDITION CODES 



E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FEXIST, 
E$FNEXIST, E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$SPACE, E$TYPE. 
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H$CREATE$FILE 



HYBRID CREATE$FILE SYSTEM CALL 

The H$CREATE$FILE system call creates a new physical, stream, 
or named data file and returns a token for the new file con- 
nection. The connection can also be given a logical name and 
cataloged in the job's logical-name directory. The owner of the 
file is assumed to be the job's default user. Full owner access 
is assumed for the file, meaning bits 0-3 of the access byte 
4Tva^4<— ax^-^s^^U-to^j^e 



Bit 



1 

2 

3 
4-7 



Meaning 

Delete 

Read 

Append 

Update 

Reserved 



The H$CREATE$FILE call also assumes the file granularity is the 
same as the volume granularity and the file size (pre- 
allocation) is zero bytes. 

If a named file designated by the path parameter already 
exists, one of the following situations occurs: 

® If the "must$create" parameter is TRUE, an error con- 
dition code (E$FEXIST) is returned. 

® If the "must$create" parameter is FALSE and the path 
designates a data file, a new connection to that file is 
returned (that is, H$CREATE$FILE acts like 
H$ATTACH$FILE). 



If the "mustScreate" parameter is FALSE and the path 
designates a device or directory, an unnamed file is 
created on the corresponding device. This file is 
deleted automatically when the last connection to it is 
deleted . 

NOTE 

Any task invoking this call must have 
a priority of 32 or greater. 



connection = RQ$H$CREATE$FILE(log$name , path, must$create, 

excepSptr ) ; 



INPUT PARAMETERS 



log$name 



is a pointer to the string giving the 
logical name under which the new con- 
nection will be cataloged in the job's 
logical-name directory. A zero in this 
parameter or a null string specifies the 
connection will not be given a logical 
name. 
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H$CREATE$FILE (continued) 



INPUT PARAMETERS (continued) 
path 



is a pointer to the string giving the 
prefix and subpath for the file being 
created. 

is a boolean whose TRUE or FALSE setting 
determines the handling of input paths 
designating an existing named file. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



must$create 

excep$ptr 

RETURN VALUE 
connection 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FEXIST, 
E$FNEXIST, E$FTYPE, E$IO, E$LIMIT, E$MEM, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$SPACE , E$TYPE. 



is a token for the connection to the newly 
created file. 
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H$DELETE$CONNECTION 

HYBRID DELETE$CONNECTION SYSTEM CALL 

The H$DELETE$CONNECTION system call severs the file connection 
established by H$CREATE$FILE , H$CREATE$DIRECTGRY, or 
H$ATTACH$FILE. It frees the connection object and also deletes 
the associated file if the file is already marked for deletion 
and if the deleted connection was the last remaining connection 
to the file. If a connection is open when H$DELETE$CONNECTION 
irs^^^^^^erj^ iii^rs^ciros-exMDei^oTe-ijeTrn-g— s^ev-ered^.^ 



CALL RQ$H$DELETE$CONNECTION(connection, excepSptr) ; 



INPUT PARAMETERS 

connection is a token for the connection to be 

deleted. 

excepSptr is a pointer to the location that receives 

the condition code resulting from this 
call . 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$IO, E$LIMIT, E$MEM, 
E$NOT$CONFIGURED. 
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H$DELETE$FILE 



HYBRID DELETE$FILE SYSTEM CALL 



The H$DELETE$FILE system call applies to stream and named files 
only. When called, it marks the designated file for deletion. 
The file will not actually be deleted, however, until all 
connections to the file have been severed (by calls to 
H$DELETE$CONNECTION) . Directory files cannot be deleted unless 
they are empty. 

The caller is assumed to be the default user for the job. 



CALL RQ$H$DELETE$FILE(path, excepSptr); 



INPUT PARAMETERS 
"path 

excep$ptr 



is a pointer to the string giving the 
prefix and subpath to the file being 
deleted . 

is a pointer to the location that receives 
the condition code resulting from this 
call . 



FILE ACCESS REQUIREMENT 

The caller must have delete access to the file. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FNEXIST, 
E$FTYPE,E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$TYPE. 
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H$GET$FILE$STATUS 

HYBRID GET$FILE$STATUS SYSTEM CALL 

The H$GET$FILE$STATUS system call returns status and attribute 
information about the designated file. Certain common infor- 
mation is returned regardless of the file driver type (physi- 
cal, stream, or named). Additional information is returned for 
named files. 

4^^4-8 — t-ha4 — t-his — G^-l-I — te4^uxn-s s-ome dje^dj: e-^^ap-exulexLt irLfLoxiri^at^ixLnL,^ 



and its use may cause an application to become device dependent. 



CALL RQ$H$GET$FILE$STATUS(path, f ile$info$ptr , excep$ptr); 



INPUT PARAMETERS 
path 

file$info$ptr 

excepSptr 

RETURN STRUCTURES 
commonSinfo 



is a pointer to the string giving the 
prefix and subpath to the file whose 
status is sought. 

is a pointer to the location that receives 
the common (and named file) status infor- 
mation . 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



is the common file-status information 
returned. This information is structured 
as follows: 



DECLARE 




common$inf 


STRUCTURE( 


dev$share 


BYTE, 


num$conn 


WORD, 


num$reader 


WORD, 


num$writer 


WORD, 


open$share 


BYTE, 


named$f ile 


BYTE, 


dev$name (14) 


BYTE, 


file$drivers 


WORD, 


functs 


WORD, 


dev$gran 


WORD, 


dev$size 


DWORD, 


dev$conn 


WORD 
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H$GET$FILE$STATUS (continued) 



RETURN STRUCTURES 
common$info (continued) 



These fields are interpreted as follows: 

dev$share indicates whether the device 
where this file resides is 
sharable or nonsharable. 
Possible values are: 

Sharable device 

1 Nonsharable device 



num$conn 
num$reader 
num$writer 
open$share 



named$file 



is the number of connections 
to the file. 

is the number of connections 
currently open for reading. 

is the number of connections 
currently open for writing. 

is the current shared status 
of the file. Possible values 
are: 

Private use only 

1 Share with readers only 

2 Share with writers only 

3 Share with all users 



specifies whether the file is 
a named file and, therefore, 
whether file$info$ptr wil 
contain named-file, as well 
as common information. A 
value of 0FFH indicates the 
additional information is 
present. 

dev$name is the name of the device 
where this file resides, null 
padded . 

fileSdrivers indicates which file drivers 
can be used with the file. If 
bit n is on, then file driver 
n+1 can be used. Bits are 
numbered right to left 
starting with zero. 
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RETURN STRUCTURES 
common$info (continued) 



Bit Driver No. 
1 



Driver 

Physical file 
Stream file 
reserved 
Named file 



functs 



devSgran 
dev$size 
dev$conn 



describes the functions 
supported by the device where 
this file resides. Each bit 
set to one indicates the 
corresponding function is 
supported. 

Bit Function 

F$READ 

1 F$WRITE 

2 F$SEEK 

3 F$SPECIAL 

A F$ATTACH$DEV 

5 F$DETACH$DEV 

6 F$OPEN 

7 F$CLOSE 
8-15 Reserved 

is the device granularity, in 
bytes. 

is the size of the device, in 
bytes . 

is the number of connections 
to the device. 



named$f ile$info 



is the additional information returned if 
the designated file is a named file. This 
information' is structured as follows: 



DECLARE 
named$f ile$info 
fdesc$num 
file$type 
file$gran 
owner (14) 
create$time (16) 
access$time (16) 
mod$time (16) 
file$size 
fileiblocks 
vol$name (16) 
vol$gran 
vol$size 
id$count 
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WORD, 
BYTE, 
BYTE, 
BYTE, 
BYTE, 
BYTE, 
BYTE, 
DWORD, 
DWORD, 
BYTE, 
WORD, 
DWORD, 
WORD, 
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H$GET$FILE$STATUS (continued) 



RETURN STRUCTURES 
named$file$info (continued) 



); 



accessor (*) 
access 
id 



STRUCTURE( 
BYTE, 
WORD) 



These fields are interpreted as follows: 



f desc$num 



file$type 



is the number of the file's 
file descriptor. The file 
descriptor is an I/O system 
data structure containing 
file attribute and status 
data. 

indicates the type of the 
file. A file with type other 
than FT$DATA (data file, 
type = 8) may only be accessed 
from within the I/O system. 



file$gran 



specifies 
granularity . 



the 



file 



owner 



is the ASCII name of the 
file's owner. 



create$time is the time and date when the 
file was created. 

access$time is the time and date when the 
file was last accessed. 



mod$time 

file$size 

file$blocks 

vol$name 

vol$gran 

vol$size 



is the time and date when the 
file was last modified. 

is the total size, in bytes, 
of the data in the file. 

is the number of volume 
blocks allocated to this file. 

is the ASCII name for the 
volume containing this file. 

is the volume granularity, in 
bytes . 

is the size of the volume, in 
bytes . 



8-67 



'/mm/' 



INVOKING I/O SYSTEM CALLS IN PL/M 
H$GET$FILE$STATUS (continued) 



RETURN STRUCTURES 
named$file$info (continued) 



id$count is the number of access/ 
user-ID pairs declared for 
this file. These pairs are 
detailed in the structure 

tiiat^jfjCLLlaYLS_. 



accessor is a list of up to three 
access/user-ID pairs. 



CONDITION CODES 



E$OK, E$BAD$CALL, E$EXIST, E$FLUSHING, E$LIMIT, E$MEM, 
E$NOT$CONFIGURED, E$TYPE. 
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H$LOOK$UP$CONNECTION 

HYBRID LOOK$UP$CONNECTION SYSTEM CALL 

The H$LOOK$UP$CONNECTION system call returns information about 
a file connection to the caller. The caller can specify a 
conection's logical name to this system call and receive the 
token associated with that connection in return. The I/O system 
looks for the name first in the job's logical-name directory. 
If the name is not found, it then looks in the global directory 
for the job, and finally in the system's logical-name direc- 
tory. If the name does not reside in either directory, an 
exception code is returned. 



connection = RQ$H$LOOK$UP$CONNECTION( log$name, excep$ptr); 



INPUT PARAMETERS 
log$name 

excepSptr 

RETURN VALUE 

connection 

CONDITION CODES 

E$OK, E$BAD$CALL, 
E$PARAM, E$TYPE. 



is a pointer to the string giving the 
logical file name to be looked up. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



is a token for the connection associated 
with the specified logical name. 

E$CONTEXT, E$EXIST, E$NOT$CONFIGURED , 
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H$RENAME$FILE 



HYBRID RENAME$FILE SYSTEM CALL 

The H$RENAME$FILE system call 
is called to change the name 
which it is cataloged in its 
file can also be recataloged 
so long as that directory is 
original parent. A directory 
its parent directory, however. 



applies to named files only. It 
of a file (that is, the name by 
parent directory). A renamed data 
in a different parent directory, 
on the same volume as the file's 
file can only be renamed within 



The caller is assumed to be the default user for the job. 



CALL RQ$H$RENAME$FILE(old$path, new$path, excepSptr); 



INPUT PARAMETERS 



old$path 



new$path 



excepSptr 



is a pointer to the string giving the 
prefix and subpath to the file being 
renamed . 

is a pointer to the string giving a new 
prefix and subpath for the file. This 
parameter must specify a nonexistent file. 
For a data file, it may specify a dif- 
ferent directory than the original parent, 
but the new parent must be on the same 
volume. For a directory file, however, the 
original parent must be retained. 

is a pointer to the location that receives 
the condition code resulting from this 
call . 



FILE ACCESS REQUIREMENTS 

The caller must have delete access to the original file and 
must have add-entry access to the file's parent directory. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FEXIST, 
E$FLUSHING, E$FNEXIST, E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, 
E$NOPREFIX, E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$SUPPORT, 
E$TYPE. 
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INSPECT$PACKAGE 



INSPECT$PACKAGE SYSTEM CALL 



INSPECT$PACKAGE is called to expand the contents of a package 
object previously created by the loader or other source. 



CALL RQ$INSPECT$PACKAGE(package, tok$list$ptr , excep$ptr); 



INPUT PARAMETERS 
package 
tok$list$ptr 



excepSptr 



is a token for the package to be inspected. 

is the structure that lists the tokens 
contained in the package object. This 
information is returned in the following 
form : 



DECLARE 
token$list 
num$slots 
num$tokens 
tokens (*) 

); 



STRUCTURE( 
WORD, 
WORD, 
WORD 



These fields are interpreted as follows: 



num$slots 



num$tokens 



contains the number of 
tokens slots in the list. 

is the actual number of 
tokens contained in the 
package object. 

INSPECT$PACKAGE will never 
store more tokens than the 
space alotted in num$slots. 

is a contiguous series of 

words, each containing one 

of the tokens making up the 
package object. 



is a pointer to the location that receives 
the condition code resulting from this 
call . 



tokens 
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S$ATTACH$FILE 

SYNCHRONOUS ATTACH$FILE SYSTEM CALL 

The S$ATTACH$FILE system call creates a composite connection to 
an existing file, including buffers needed for synchronous I/O 
operations on the connection. The composite connection formed 
can be given a logical name and cataloged in the calling job's 
logical-name directory. 

J1ie„_'LbjjJff$ s J.zje^L_p_a-r-a I 
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different, actual buffer size can be specified by S$OPEN when 
the connection is opened. 

The caller is assumed to be the default user for the job. 

NOTE 



Any task invoking this call must have a 
priority of 32 or greater. 



connection = RQ$S$ATTACH$FILE(log$name , path, buff$size 

num$buff, excep$ptr); 



INPUT PARAMETERS 



log$name 



path 



is a pointer to the string giving the 
logical name under which the composite 
object (high-level connection) is to be 
cataloged in the job's logical-name direc- 
tory. A zero in this parameter or a null 
string indicates that the object should 
not be cataloged. 

is a pointer to the string giving the 
prefix and subpath of the file to be 
attached . 



buf f$size 



num$buf f 



excepSptr 



is a word giving the default SIOS (or 
user) buffer size (in bytes). A zero 
indicates that the buffer size should be 
the same as the file granularity. 

is a byte giving the default number of 
SIOS buffers to be used. The maximum 
allowed is two. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



RETURN VALUE 
connection 



is a token for the composite object (high- 
level connection) attached to the file. 
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S$ATTACH$FILE (continued) 



CONDITION CODES 



E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FNEXIST, E$FTYPE, E$IO, 
E$LIMIT, E$MEM, E$NOBUFF, E$NOPREFIX, E$NOT$CONFIGURED , 
E$NOUSER, E$NUMBUFF, E$PARAM, E$TYPE,. 
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S$CHANGE$ACCESS 



SYNCHRONOUS CHANGE$ACCESS SYSTEM CALL 

The S$CHANGE$ACCESS system call applies to named files only. It 
is called to change the access rights to a named data or direc- 
tory file. The caller is assumed to be the default user. 

NOTE 

^u^rafltl-y-, — all u s ^rs— h a-VAe— aGC^sg-s-^to— al-1— fl-l-a^^ 



at the synchronous level. The new access rights 

specified in this call will apply to all users, 

including the caller. 



CALL RQ$S$CHANGE$ACCESS(path, mode, name, access, excep$ptr); 



INPUT PARAMETERS 



path 

mode 
name 



is a pointer to the string giving the 
prefix and subpath to the file whose 
access rights are to be changed. 

is a byte value, currently ignored. 

is a pointer to the string giving the name 
of the accessor whose rights are being 
added, deleted, or changed. Currently, 
this string must be "WORLD," which 
includes all users. 



access 



is a BYTE mask giving the new access 
rights for the specified accessor. If a 
bit is set to one, the corresponding 
access is granted. For a named data file, 
the possible bit settings are: 



Bit 


Meaning 





Delete 


1 


Read 


2 


Append 


3 


Update 


A-7 


Reserved 



For a named directory file, the possible 
bit settings are: 



Bit 



1 

2 

3 
4-7 



Meaning 
Delete 
Display 
Add Entry 
Change Entry 
Reserved 
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S$CHANGE$ACCESS (continued) 



INPUT PARAMETERS (continued) 



excepSptr 



is a pointer to the location that receives 
the condition code resulting from this 
call . 



FILE ACCESS REQUIREMENTS 

The caller must be the owner of the file or must have change- 
entry access to the file's parent directory. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FLUSHING, 
E$FNEXIST, E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM , E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$TYPE. 
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S$CLOSE 

SYNCHRONOUS CLOSE SYSTEM CALL 

The S$CLOSE system call closes an open composite connection, 
including the buffers associated with that connection. It 
performs the following steps: 

waits for I/O operations in progress to be completed. 

% makes sure that all data in the b uffer of an output file 



is completely written if the buffer is partially filled. 
releases the buffer(s) created by S$OPEN. 
closes the file connection. 



CALL RQ$S$CLOSE(connection, excepSptr); 



INPUT PARAMETERS 
connection 

excepSptr 
CONDITION CODES 



is a token for the open composite con- 
nection to be closed. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



E$OK, E$BAD$CALL, E$CANNOT$CLOSE , E$CONTEXT, E$EXIST, 
E$FLUSHING, E$LIMIT, E$MEM, E$NOT$CONFIGURED , E$TYPE. 
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S$CREATE$DIRECTORY 

SYNCHRONOUS CREATE$DIRECTORY SYSTEM CALL 

The S$CREATE$DIRECTORY system call applies to named directory 
files only. When called, it creates, a new directory file. The 
new connection can also be cataloged under a specified logical 
name in the job's logical-name directory. 

The caller is assumed to be the default user for the job. Full 
owner access to the directory is assumed; that is, bits 0-3 in 
the access byte mask are all set to one. 



Bit 



1 

2 

3 
4-7 



Meaning 
Delete 
Display 
Add Entry 
Change Entry 
Reserved 



NOTE 

Any task invoking this call must have 
a priority of 32 or greater. 



connection = RQ$S$CREATE$DIRECTORY(log$name , path, excep$ptr) ; 



INPUT PARAMETERS 
log$name 



path 



excep$ptr 



is a pointer to the string giving the 
logical name under which the new con- 
nection is to be cataloged in the job's 
logical-name directory. A zero in this 
parameter or a null string specifies that 
the connection is not to be given a 
logical name. 

is a pointer to the string containing the 
prefix and subpath to the directory being 
created. This string cannot be null, and 
the directory name cannot exist already. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



RETURN VALUE 



connection 



is a token for the connection to the new 
directory file. 



FILE ACCESS REQUIREMENT 

The caller must have add-entry access to the parent of the new 
directory. 
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S$CREATE$DIRECTORY (continued) 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FEXIST, 
E$FNEXIST, E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$SPACE , E$TYPE. 
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S$CREATE$FILE 



SYNCHRONOUS CREATE$FILE SYSTEM CALL 

The S$CREATE$FILE system call creates a new physical, stream or 
named data file. It also creates a composite connection to the 
file including a token from a segment giving the number and 
size of SIOS buffers to be used in I/O operations on the file. 
The token for this connection is returned by the S$CREATE$FILE 
call. The connection can also be given a: logical name and 
cataloged in the job's logical-name directory. 

The owner of the file is assumed to be the job's default user. 
Full owner access is assumed, meaning bits 0-3 of the access 
byte mask are set to one. 



Bit 



1 

2 

3 
4-7 



Meaning 

Delete 

Read 

Append 

Update 

Reserved 



The S$CREATE$FILE calls also assumes the file granularity is 
the same as the volume granularity and the file size (pre- 
allocation) is zero bytes. 

If a named file designated by the path parameter already 
exists, one of the following situations occurs; 



If the "mustScreate" parameter is TRUE, an 
dition code (E$FEXIST) is returned. 



error con^ 



If the "must$create" parameter is FALSE and the path 
designates a data file, a new connection to that file is 
returned (that is, S$CREATE$FILE acts like 
S$ATTACH$FILE) and the file is truncated to zero length. 

If the "must$create" parameter is FALSE and the path 
designates a device or directory, an unnamed file is 
created on the corresponding device. This file is 
deleted automatically when the last connection to it is 
deleted . 

NOTE 



Any task invoking this call must have a 
priority of 32 or greater. 



connection = RQ$S$CREATE$FILE( log$name , path, buff$size, 

num$buff, must$create, 
excepSptr ) ; 
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S$CREATE$FILE (continued) 



INPUT PARAMETERS 
log$name 



is a pointer to the string giving the 
logical name under which the new con- 
nection is to be cataloged in the job's 
logical-name directory. A zero in this 
parameter or a null string specifies that 
±he CO n aec t i on is aoJt tjo bje gjLvjeD a^ 



path 



buf f$size 



num$buf f 

must$create 

excepSptr 

RETURN VALUE 
connection 

CONDITION CODES 



logical name. 

is a pointer to the string giving the 
prefix and subpath for the file being 
created. 

is a word giving the default size (in 
bytes) of any SIOS buffers created. A zero 
indicates that the buffer size is the same 
as the file granularity for a named file, 
the device granularity for a physical 
file, and the folume granularity for a 
stream file. 



is a byte giving the 
SIOS buffers to be 
allowed is two. 



default number of 
used. The maximum 



is a boolean whose TRUE or FALSE setting 
determines the handling of input paths 
designating an existing named file. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



is a token for the 
level connection) 
file. 



composite object (high- 
for the newly created 



E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FEXIST, 
E$FNEXIST, E$FTYPE, E$IO, E$LIMIT, E$MEM, E$NOBUFF, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$NUMBUFF , E$PARAM, E$SPACE, E$TYPE. 
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S$DELETE$CONNECTION 



SYNCHRONOUS DELETE$CONNECTION SYSTEM CALL 



The S$DELETE$CONNECTION system call severs the composite file 
connection created by S$CREATE$FILE or S$ATTACH$FILE . It frees 
the composite connection object. It also deletes the file if 
the file is already marked for deletion, and if the specified 
connection is the last remaining connection to the file. If the 
connection is open when S$DELETE$CONNECTION is called, it is 
closed before being severed. 



CALL RQ$S$DELETE$CONNECTION(connection, excepSptr); 



INPUT PARAMETERS 



connection 



excep$ptr 



is a token for the composite connection 
object to be severed. 

is a pointer to the location that receives 
the condition code resulting from this 
call . 



CONDITION CODES 



E$OK, E$BAD$CALL, E$CONTEXT, 
E$NOT$CONFIGURED, E$TYPE. 



E$EXIST, E$IO, E$LIMIT, E$MEM, 
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S$DELETE$FILE 



SYNCHRONOUS DELETE$FILE SYSTEM CALL 

The S$DELETE$FILE system call applies to stream and named files 
only. When called, it marks the designated file for deletion. 
The file will not actually be deleted, however, until all 
connections to the file have been severed (by calls to 
S$DELETE$CONNECTION) . Directory files cannot be deleted unless 
they are empty. 

The caller is assumed to be the default user for the job. 



CALL RQ$S$DELETE$FILE(path, excep$ptr); 



INPUT PARAMETERS 
path 

excepSptr 



is a pointer to the string giving the 
prefix and subpath to the file being 
deleted . 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



FILE ACCESS REQUIREMENT 

The caller must have delete access to the file. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FNEXIST, 
E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOPREFIX, 
E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$TYPE. 
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SET$DEFALULT$PREFIX 

SET$DEFAULT$PREFIX SYSTEM CALL 

The SET$DEFAULT$PREFIX system call sets the default prefix for 
an existing job. A job created by calling CREATE$IO$JOB can 
have its default prefix set at the time it is created. 



CALL RQ$SET$DEFAULT$PREFIX( job, prefix, excepSptr); 



INPUT PARAMETERS 
job 

prefix 
excepSptr 

CONDITION CODES 



is a token for the job whose default 
prefix is to be set. A zero specifies the 
current job. 

is a token for the connection that is to 
become the default prefix. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



E$OK, E$BAD$CALL, E$EXIST, E$LIMIT, E$MEM, E$NOT$CONFIGURED , 
E$TYPE. 
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SET$DEFAULT$USER 
SET$DEFAULT$USER SYSTEM CALL 

The SET$DEFAULT$USER system call sets the default user for an 
existing job. A job created by calling CREATE$IO$JOB can have 
its default user set at the time it is created. 



CALL RQ$SET$DEFAULT$USER( job, user, excep$ptr); 



JJvlRUJL_RAR^M^ETERS^ 



job 



user 



is a token for the job whose default user 
object is to be set. A zero designates the 
current job. 

is a token for the user object that is to 
become the default user. 



excepSptr 



is a pointer to the location that receives 
the condition code resulting from this 
call. 



CONDITION CODES 

E$OK, E$BAD$CALL, E$EXIST, E$LIMIT, E$MEM, E$NOT$CONFIGURED , 
E$TYPE. 
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S$GET$CONNECTION$STATUS 

SYNCHRONOUS GET$CONNECTION$STATUS SYSTEM CALL 

S$GET$CONNECTION$STATUS is called to obtain status information 
associated with the designated connection. 



CALL RQ$S$GET$CONNECTION$STATUS(connection, conn$info$ptr , 

excepSptr ) ; 



INPUT PARAMETERS 
connection 

conn$info$ptr 
excep$ptr 

RESULT SEGMENT 
conn$info 



is a token for the connection whose status 
is sought. 

is a pointer to the location that receives 
the status information. 

is a pointer to the location that receives 
the condition code resulting from this 
call . 



is the desired status 
structured as follows: 



information , 



DECLARE 
conn$info 
flags 
open$mode 
open$share 
file$pointer 
access 
num$buf f 
buf f$size 
seek 

); 



STRUCTURE 
BYTE, 
BYTE, 
BYTE, 
DWORD, 
BYTE, 
BYTE, 
WORD, 
BOOLEAN 



These fields are interpreted as follows: 

flags contains two flag bits. If 
bit 1 is set to one, this is 
an active connection and can 
be opened. If bit 2 is set, 
this is a device or direc- 
tory file connection. 

open mode is the mode established when 
this connection was opened. 
Possible values are: 
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S$GET$CONNECTION$STATUS (continued) 



RESULT SEGEMENT 
conn$info (continued) 



Connection is closed 

1 Open for reading only 

2 Open for writing only 

3 Open for reading and 
w r i t jLag 



open$share 



is the shared status estab- 
lished when this connection 
was opened. Possible values 
are : 



Private use only 

1 Share with readers only 

2 Share with writers only 

3 Share with all users 

fileSpointer gives the pointer's current 
byte location in the file. 



access 



gives the access rights for 
this connection. Possible 
settings of the byte mask 
are : 



num$buf f 



Bit 



1 

2 

3 
4-7 



Access 

Delete 

Read 

Append 

Update 

Reserved 



is the number of buffers 
specified for read and write 
operations on this con- 
nection . 



buf f$size 



seek 



is the size 
the buffers, 
buffer size 
specified 
S$CREATE$FILE 
S$ATTACH$FILE 



(in bytes) of 
The default 

is the size 

in the 

or 

call that 



created this connection. 



if TRUE, indicates the SEEK 
function is supported; If 
FALSE, indicates the SEEK 
function is not supported. 
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S$GET$CONNECTION$STATUS (continued) 



CONDITON CODES 

E$OK, E$BAD$CALL, E$EXIST, 
E$NOT$CONFIGURED, E$TYPE. 



E$FLUSHING, E$LIMIT, E$MEM, 
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S$GET$FILE$STATUS 

SYNCHRONOUS GET$FILE$STATUS SYSTEM CALL 

The S$GET$FILE$STATUS system call returns status and attribute 
information about the designated file. Certain common in- 
formation is returned regardless of the file driver type 
(physical, stream or named). Additional information is returned 
for named files. 

Note that this c_alJ. reJLuxas SJOJne ^devXc-e^^depenxLeat — In^xnmtiofl-,- 

and its use may cause an application to become device dependent. 



CALL RQ$S$GET$FILE$STATUS(path, f ile$inf o$ptr , excep$ptr); 



INPUT PARAMETERS 



path 

file$info$ptr 

excep$ptr 

RETURN STRUCTURES 
common$info 



is a pointer to the string giving the 
prefix and subpath to the file whose 
status is sought. 

is a pointer to the location that receives 
the common (and named file) status in- 
formation. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



is the common file-status information 
returned. This information is structured 
as follows: 



DECLARE 




common$info 


STRUCTURE( 


dev$share 


BYTE, 


num$conn 


WORD, 


num$reader 


WORD, 


num$writer 


WORD, 


open$share 


BYTE, 


named$file 


BYTE, 


dev$name (14) 


BYTE, 


file$drivers 


WORD, 


functs 


WORD, 


devSgran 


WORD, 


dev$size 


DWORD, 


dev$conn 

); 


WORD 



These fields are interpreted as follows: 

dev$share indicates whether the device 
where this file resides is 
sharable or nonsharable. 
Possible values are: 
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S$GET$FILE$STATUS (continued) 



RETURN STRUCTURES 
common$info (continued) 



numSconn 
num$reader 
num$writer 
open$share 



named$file 



dev$name 



file$drivers 



functs 



Sharable device 

1 Nonsharable device 

is the number of connections 
to the file. 

is the number of connections 
currently open for reading. 

is the number of connections 
currently open for writing. 

is the current shared status 
of the file. Possible values 
are : 

Private use only 

1 Share with readers only 

2 Share with writers only 

3 Share with all users 

specifies whether the file 
is a named file and, there- 
fore, whether file$info$ptr 
will contain named-file, as 
well as common information. 
A value of 0FFH indicates 
the additional information 
is present. 



is the name 
where this 
null padded. 



of the device 
file resides, 



indicates which file drivers 
can be used with the file. 
If bit is on, then file 
driver n + 1 can be used. Bits 
are numbered right to left 
starting with zero. 



Bit Driver No. 
■ " 
1 
2 



Drivers 
Physical file 
Stream file 
reserved 
Named file 



describes the functions 
supported by the device 
where this file resides. 
Each bit set to one indi- 
cates the corresponding 
function is supported. 
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RETURN STRUCTURES 
common$info 
functs (continued) 



Bit 



Function 
F$READ 
F$WRITE 

— F$5-EEK~ 



3 
4 
5 
6 
7 
8-15 



F$SPECIAL 

F$ATTACH$DEV 

F$DETACH$DEV 

F$OPEN 

F$CLOSE 

Reserved 



dev$gran 
dev$size 
dev$conn 



is the device granularity, 

in bytes. 

is the size of the device, 

in bytes. 

is the number of connections 

to the device. 



named$file$info is the additional information returned if 

the designated file is a named file. This 
information is structured as follows: 



DECLARE 
named$file$info 
fdesc$num 
file$type 
fileSgran 
owner (14) 
create$time (16) 
access$time (16) 
mod$time (16) 
file$size 
file$blocks 
vol$name (6) 
vol$gran 
vol$size 
id$count 
accessor (*) 

access 

id 

); 



STRUCTURE( 

WORD, 

BYTE, 

BYTE, 

BYTE, 

BYTE, 

BYTE, 

BYTE, 

DWORD, 

DWORD, 

BYTE, 

WORD, 

DWORD, 

WORD, 

STRUCTURE( 
BYTE, 
WORD) 



These fields are interpreted as follows 
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S$GET$FILE$STATUS (continued) 



RETURN STRUCTURES 
named$file$info (continued) 

fdesc$num 



file$type 



file$gran 

owner 

create$time 

access$time 

mod$time 

file$size 

file$blocks 

vol$name 
vol$size 
id$count 



is the number of the file's 
file descriptor. The file 
descriptor is an I/O system 
data structure containing 
file attribute and status 
data. 

indicates the type of the 
file. A file with type other 
than FT$DATA (data file, 
type = 8) may only be accessed 
from within the I/O system. 

specifies the file granu- 
larity . 



is the ASCII 
file's owner. 



nme 



of the 



accessor 



is the time and date when 
the file was created. 

is the time and date when 
the file was last accessed. 

is the time and date when 
the file was last modified. 

is the total size, in bytes, 
of the data in the file. 

is the number of volume 
blocks allocated to this 
file. 

is the ASCII name for the 
volume containing this file. 

is the size of the volume, 
in bytes. 

is the number of access/ 
user-ID pairs declared -for 
this file. These pairs are 
detailed in the structure 
that follows. 

is currently limited to 
"WORLD". 
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S$GET$FILE$STATUS (continued) 



CONDITION CODES 

E$OK, E$BAD$CALL, E$EXIST, 
E$NOT$CONFIGURED, E$TYPE. 



E$FLUSHING, E$LIMIT, E$MEM, 



8-92 



INVOKING I/O SYSTEM CALLS IN PL/M 



S$LOAD 



SYNCHRONOUS LOAD SYSTEM CALL 



S$LOAD is called to load an 8086 object file into memory during 
job execution. Object files must be located by L0C86 before 
they can be loaded. The user must be certain that all absolute 
address assignments are in a space he has reserved for this 
purpose during system configuration. 

S$LOAD can also create a new job for the object file being 
loaded, as well as a new task for executing the file. If no new 
task is created, S$LOAD returns register initialization values 
for the loaded task. 



job = RQ$S$LOAD( job$data$ptr , prefix$ptr, log$names$ptr , 

task$flags, task$prior, load$function , 
path, return$data$ptr, excep$ptr); 



INPUT PARAMETERS 

job$data$ptr is a pointer to the job data structure 

defined below. This structure is used only 
if a new job is to be created and is 
ignored otherwise. 

prefix$ptr is a pointer to a string giving the 

default prefix for the job (specified as a 
logical name). A null string or zero 
pointer specifies that the calling job's 
default prefix is to be used. 

log$names$ptr is a pointer to a contiguous set of 

string/token pairs, each giving a logical 
name to be inherited by the new job from 
its creator. A zero token assoicates its 
corresponding string with the parent job's 
token for the same string. 

task$flags is a word containing information about the 

initial task in the new job. 

task$prior is a byte specifying the priority of the 

new task. This priority must be lower 
(higher numerically) or equal to the 
parent job's maximum priority. A zero 
specifies that the task has the highest 
priority allowed by its job. 

load$function is a byte specifying the function to be 

done : 

Create new job and initial task 

1 Load into calling job and create task 

2 Load into calling job and return 
register initialization values 
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S$LOAD (continued) 



INPUT PARAMETERS (continued) 



path 



is a pointer to the string giving the 
prefix and subpath of the object file to 
be loaded. 



return$data$ptr is a pointer to the buffer that receives a 
re^4iXt--S-agmeai^-vthjexi^S4tLJDj^_ijs_JLLjD_i^h£d^ 



excep$ptr 



is a pointer to the location that receives 
the condition code resulting from this 
call . 



The job$data$ptr parameter must point to a previously-defined 
structure of the following form: 



where: 



dir$size 
param$obj 
min$job$size 
max$job$size 



DECLARE 
job$data 
dir$size 
param$obj 
min$job$size 
max$job$size 
max$objects 
max$tasks 
max$prior 
excep$hdler$o 
excep$hdler$b 
excep$mode 
jobSflags 
globalSjob 
user 
msg$mbox 

); 



STRUCTURE( 
WORD, 
TOKEN, 
WORD, 
WORD, 
WORD, 
WORD, 
BYTE, 
ffset WORD, 
ase WORD, 
BYTE, 
WORD, 
TOKEN, 
TOKEN, 
TOKEN 



is a word containing the maximum number of 
entries in the created job's object 
directory . 

is the token for the created job's 
parameter object. A zero specifies that 
the job does not have a parameter object. 

is the minimum size, in 16-byte pages, of 
the newly-created job's memory pool. It is 
also the initial size of the pool. 

is the maximum pool size, in 16-byte 
pages, allowed for the new job. 
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S$LOAD (continued) 



INPUT PARAMETERS 
where: (continued) 

max$objects 



max$tasks 



max$prior 



excep$hdler$of fset 
excep$hdler$base 



job$flags 



global$job 



user 



msg$mbox 



RETURN VALUE 
job 



is a word containing the maximum number 
of objects that this job can contain 
simultaneously. 0FFFFH specifies an 
unlimited number. 

is a word containing the maximum number 
of tasks that can exist simultaneously 
within this job. 0FFFFH specifies an 
unlimited number. 

is a byte specifying this job's maximum 
task priority from (high) to 255 
(low). A zero specifies that the max- 
imum priority equals the maximum task 
priority of the calling job. 

point to the first instruction of the 
job's default exception handler. Zeros 
specify that the system default excep- 
tion handler is to be used. 

contains job information needed by the 
RMX/86 nucleus. If any tasks in the job 
use the 8087 component, the low-order 
bit should be set to one. 

is a token for a job whose object 
directory is to be used as the global 
logical-name directory for the job 
being created. A zero specifies that 
the caller's global job is to be used. 

is a token for the job's default user 
object. A zero specifies that the 
calling job's default user is the new 
job's default also. 

is a token for the mailbox that will 
receive the exit message when this job 
is exited. A zero specifies that no 
message is desired. (See EXIT$IO$JOB 
for exit message formats. 



is a token for the job created by the 
loader, or zero if no job was created. 
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RESULT SEGMENT 
result$seg 



is the result segment returned to the 
location designated by return$data$ptr . The 
format of the result segment varies 
depending on the load function selected. 

-l-e-a-d-$-ftin^^-0fl^— 



DECLARE 




resultSseg STRUCTURE( 


status 


WORD, 


error$displace 


DWORD, 


error$rec$type 


BYTE, 


num$undef$refs 


WORD, 


mem$req 


WORD, 


mem$received 
); 


WORD 


load$function = 1 





DECLARE 

result$seg 
status 

error$displace 
error$rec$type 
num$undef$refs 
task$token 

); 



STRUCTURE( 
WORD, 
DWORD, 
BYTE, 
WORD, 
TOKEN, 



where : 

status 



load$function = 2 

DECLARE 

result$seg 

status 

error$displace 

error$rec$type 

num$undef$refs 

init$CS 

init$IP 

init$SS 

stack$of fset 

stack$size 

init$DS 

); 



STRUCTUREC 
WORD, 
DWORD, 
BYTE, 
WORD, 
TOKEN, 
WORD, 
TOKEN, 
WORD, 
WORD, 
TOKEN 



indicates whether 
terminated normally 
error (E$IO). 



the load operation 
(E$OK) or due to an 
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S$LOAD (continued) 



RESULT SEGMENT 
where: (continued) 

error$displace if nonzero, defines the displacement within 

the file of an erroneous object record. 

error$rec$type if nonzero, gives the record type of the 

erroneous object record. 

num$undef$refs is the number of undefined external ref- 
erences encountered during the load. 



mem$req 
mem$received 

task$token 
init$CS 

initSiP 

init$SS 

stack$of fset 
stack$size 

init$DS 
CONDITION CODES 



is the desired maximum memory size. 

is the number of 16-byte pages actually 
allocated to the new job. 

is the token for the newly-created task. 

is the initial value of the loaded task's 
CS register. It is zero if the register is 
not initialized in the object file. 

gives the initial value of the loaded 
task's IP register. It is zero if not 
initialized in the object file. 

is a token used to initialize the loaded 
task's SS register. It is zero if the 
register is not initialized in the object 
file. 

gives the location of the bottom of the 
stack relative to SS. It is zero if not 
initialized. 

gives the size of the stack. The loaded 
task's stack pointer should be initialized 
to the sum of stack$offset and stack$size. 
This field is zero if not initialized. 

is a token used to initialize the task's DS 
register. It is zero if not initialized in 
the object file. 



E$OK, E$ABS$ADDRESS, E$BAD$GRP, E$BAD$HDR, E$BAD$SEG, 
E$CHECKSUM, E$EOF, E$FIXUP, E$LFUNC, E$NO$LMEM, E$NO$MEM, 
E$REC$FMT, E$REC$LENGTH, E$REC$TYPE, E$REG$INIT, E$SEG$ALLOC. 
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S$LOOK$UP$CONNECTION 

SYNCHRONOUS LOOK$UP$CONNECTION SYSTEM CALL 

The S$LOOK$UP$CONNECTION system call returns information about 
a file conection to the caller. The caller can specify a con- 
nection's logical name to this system call and receive the 
token associated with that connection in return. The I/O system 
looks for the name first in the job's logical-name directory. 
If the name is not found, it then looks in the global directory 
-fjor the loib-, a-oij fin a l 1 v lo the svs_t_eJiLLs log ical-name 



directory. If the name does not reside in either directory, an 
exception code is returned. 



connection = RQ$S$LOOK$UP$CONNECTION( log$name , excepSptr); 



INPUT PARAMETERS 
logSname 

excepSptr 

RETURN VALUE 
connection 

CONDITION CODES 



is a pointer to the string giving the 
logical file name to be looked up. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



is a token for the connection associated 
with the specified logical name. 



E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$NOT$CONFIGURED , 
E$PARAM, E$TYPE. 
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S$OPEN 

SYNCHRONOUS OPEN SYSTEM CALL 

The S$OPEN system call opens a composite file connection for 
I/O. The connection must be opened before I/O operations such 
as reading and writing can be performed. S$OPEN also initial- 
izes the connection for a particular mode of shared access. The 
following steps are performed: 

(3 create and initialize I/O buffer(s); 

• initialize the file pointer to zero; 

(D open the connection; 

check the current shared state of the connected file and 
return a condition code of this state conflicts with the 
mode of the open request; 

(B initiate the first read if the open is requested for 
reading and if at least one buffer has been created; 

check for stream file driver; if present, assume 
"num$buff" is zero. 



CALL RQ$S$OPEN(connection, mode, share, buff$size, 
num$buff, excep$ptr); 



INPUT PARAMETERS 

connection is a token for the composite connection to 

be opened. 

mode is a byte giving the mode of the open 

request. Possible values are: 

1 Read only 

2 Write only 

3 Read and write (update) 

share is a byte specifying the kind of sharing 

desired. Possible values are: 

Private use only 

1 Share with readers only 

2 Share with writers only 

3 Share with all users 

buff$size is a word giving the size (in bytes) of 

the buffer(s) to be used by the I/O 
system. A zero indicates the default 
buffer size is to be used. The default 
size is the size specified in the 
S$CREATE$FILE or S$ATTACH$FILE call that 
created this connection. 
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S$OPEN (continued) 

INPUT PARAMETERS (continued) 

num$buff is a byte specifying the number of buffers 

to be used for multiple buffering. For 
locate mode, at least one buffer is 
needed. For move mode, zero or more can be 
specified. The maximum allowed is two 
buffers. If two buffers are specified, 
multiple buffering is implied and read- 
ahead and write-ahead will be performed. 

The default value for this parameter is 
the number of buffers specified in the 
S$CREATE$FILE or S$ATTACH$FILE call that 
created this connection. The default is 
indicated by specifying 0FFH for this 
parameter . 

excep$ptr is a pointer to the location that receives 

the condition code resulting from this 
call. 

FILE ACCESS REQUIREMENT 

The current shared status of the file must be compatible with 
the requested mode of open. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FLUSHING, 
E$LIMIT, E$MEM, E$NOBUFF, E$NOT$CONFIGURED, E$NUMBUFF, E$PARAM, 
E$SHARE, E$TYPE. 
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S$READ$LOCATE 



SYNCHRONOUS READ$LOCATE SYSTEM CALL 



The S$READ$LOCATE system call reads a collection of bytes from 
a file designated by the caller. After this call has been 
completed, the location addressed by the "dataSptr" parameter 
contains a pointer to the SIOS buffer containing the bytes that 
were read. 

The actual number of bytes read is always less than or equal to 
the number of bytes requested in the system call unless an 
exceptional condition occurred. A zero is returned when an 
end-of-file was encountered and nothing was read. This is a 
normal condition and E$OK is the condition code returned. 

NOTE 

If the number of bytes being read spans two SIOS 

buffers, only the bytes in the currently active 

buffer are read. The other buffer can be read by 

issuing a second S$READ$LOCATE call. 

S$READ$LOCATE is often used in conjunction with the 
S$WRITE$UPDATE system call to update files. See the description 
of S$WRITE$UPDATE for further details. 



bytes$read = RQ$S$READ$LOCATE(connection , data$ptr, count, 

excepSptr) ; 



INPUT PARAMETERS 



connection 
dataSptr 
count 
excep$ptr 



is a token for the open connection to be 
read. 

is a pointer to the SIOS buffer to receive 
the data being read. 

is a word giving the number of bytes to be 
read. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



RETURN VALUE 



bytes$read 



is a word giving the actual number of 
bytes read. A zero indicates the end-of- 
file was reached with no bytes being read. 



FILE ACCESS REQUIREMENT 

The spcified connection must be open for reading. 
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CONDITION CODES 

E$OK, E$BADBLK, E$BAD$CALL, E$CONTEXT, E$DEVNR, E$EXIST, 
E$FATALHW, E$FLUSHING, E$IO, E$LIMIT, E$MEM, E$MIXREADMODE , 
E$NOBUFF, E$NOT$CONFIGURED, E$NUMBUFF , E$PARITY, E$TYPE. 
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S$READ$MOVE 



SYNCHRONOUS READ$MOVE SYSTEM CALL 



The S$READ$MOVE call reads a collection of bytes from a file to 
the specified caller buffer. 

The actual number of bytes read is always less than or equal to 

the number of bytes requested in the system call, unless an 

exceptional condition occurred. A zero is returned if an 

end-of-file is encountered and no bytes were read. This is a 
normal condition and returns an E$OK condition code. 



byte$read = RQ$S$READ$MOVE(connection , buff$ptr, count, 

excep$ptr) ; 



INPUT PARAMETERS 
connection 

buff$ptr 

count 

excep$ptr 

RETURN VALUE 
bytes$read 



is a token for the open connection to be 
read. 

is a pointer to the user buffer that is to 
receive the data read. 

is a word giving the number of bytes to be 
read. 

is a pointer to the location that receives 
the condition code resulting from this 
call. 



is a word giving the actual number of 
bytes read. 



FILE ACCESS REQUIREMENT 

The specified connection must be open for reading. 

CONDITION CODES 

E$OK, E$BADBLK, E$BAD$CALL, E$CONTEXT, E$DEVNR, E$EXIST, 
E$FATALHW, E$FLUSHING, E$IO, E$LIMIT, E$MEM, E$MIXREADMODE, 
E$NOBUFF, E$NOT$CONFIGURED, E$NUM$BUFF, E$PARITY, E$TYPE. 
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S$RENAME$FILE 



SYNCHRONOUS RENAME$FILE SYSTEM CALL 

The S$RENAME$FILE system call applies to named files only. It 
is called to change the name of a file (that is, the name by 
which it is cataloged in its parent directory). A renamed data 
file can be recataloged in a different parent directory, so 
long as that directory is on the same volume as the file's 
original parent. Renamed directory files must keep the same 
parent, however. 

The caller is assumed to be the default user for the job. 



CALL RQ$S$RENAME$FILE(old$path, new$path, excep$ptr) ; 



INPUT PARAMETERS 



old$path 



is a pointer to the string giving the 
prefix and subpath to the file being 
renamed . 



new$path 



is a pointer to the string giving a new 
prefix and subpath for the file. This 
parameter must specify a nonexistent file. 
For a data file, it may specify a dif- 
ferent directory than the original parent, 
but the new parent must be on the same 
volume. A directory file can only be 
renamed within its parent directory, 
however. 



excep$ptr 



is a pointer to the location that receives 
the condition code resulting from this 
call . 



FILE ACCESS REQUIREMENTS 

The caller must have delete access to the original file and 
must have add-entry access to the file's parent directory. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FEXIST, 
E$FLUSHING, E$FNEXIST, E$FTYPE, E$IFDR, E$IO, E$LIMIT, E$MEM, 
E$NOPREFIX, E$NOT$CONFIGURED, E$NOUSER, E$PARAM, E$SUPPORT, 
E$TYPE. 
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S$SEEK 

SYNCHRONOUS SEEK SYSTEM CALL 

The S$SEEK system call applies to physical and named files 
only. It moves the file pointer to the specified byte position 
in the file. The designated connection must be open at the time 
S$SEEK is called. 



CALL RQ$S$SEEK(connection, mode, hi$ptr$move, low$ptr$move , 

excepSptr) ; 



INPUT PARAMETERS 

connection is a token for the open connection file 

whose file pointer is to be moved. 

mode is a byte describing the movement of the 

file pointer. Possible values are: 

1 Move pointer back by "ptr$move" 
amount. If this action moves the 
pointer past the beginning of the 
file, the pointer is set to byte 
position zero. 

2 Set the pointer to the location 
specified by "ptr$move." 

3 Move the file pointer forward by 
"ptr$move" amount. 

4 Move the pointer to the end of the 
file, minus the "ptr$move" specified. 

hi$ptr$move is a word pair giving the position in the 
low$ptr$move file to which the file pointer is to be 

moved. The interpretation of "ptrSmove 
depends on the mode setting, as explained 
above . 

excep$ptr is a pointer to the location that receives 

the condition code resulting from this 
call. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FLUSHING, E$IFDR, E$IO, 
E$LIMIT, E$MEM, E$NOT$CONFIGURED , E$PARAM, E$TYPE. 
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S$SPECIAL 



SYNCHRONOUS SPECIAL SYSTEM CALL 

The S$SPECIAL system call applies to physical files only. It 
lets the caller perform special device-level functions. 

The special function to be done can be specified using either 
of two methods. If the function requires little supporting 
information (such as a function to rewind a magnetic tape), its 
code can be specified directly as the "spec$func" parameter in 
the system call. 

Where additional information is needed, the user must create an 
I/O parameter block as described below. The special function is 
specified indirectly, as a field in this parameter block. The 
block is then addressed by the "ioparm$ptr" in the system call. 

If only the "spec$func" parameter is used to specify the 
special function, the "ioparm$ptr" parameter is specified as 
zero. 



CALL RQ$S$SPECIAL(connection, spec$func, ioparm$ptr, 

ioresp$ptr, excep$ptr); 



INPUT PARAMETERS 



connection 



spec$func 



ioparmSptr 



iorespSptr 



excep$ptr 



is a token for a connection to the file 
where the special function is to be 
performed. 

is a word (code) that allows the user to 

pass a special function to a file driver 

without being required to set up a 
parameter block. 

is a pointer to a parameter block. The 
contents of the parameter block depends on 
the requirements of the file driver being 
used to implement the special "function. If 
the file driver requires no parameter for 
the function being requested, then the 
ioparm$ptr can be zero. If the function 
does require parameters, you must build 
the parameter block to satisfy the 
requirements of the specific file driver. 

is a pointer to the location that receives 
an I/O result segment indication that the 
special function has been completed (see 
Appendix C). A zero indicates that no 
result is wanted. 

is a pointer to the location that receives 
the condition code resulting from this 
call . 
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S$SPECIAL (continued) 



CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FLUSHING, 
E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOT$CONFIGURED, E$TYPE. 



E$IDDR, 
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S$TRUNCATE$FILE 



SYNCHRONOUS TRUNCATE$FILE SYSTEM CALL 

The S$TRUNCATE$FILE system call applies to named files only. 
When called, it truncates a file at the current setting of the 
file pointer and frees all allocated space beyond the pointer. 
S$SEEK can be called to position the file pointer before 
calling S$TRUNCATE$FILE . If the pointer is at or beyond the 
end-of-file, no operation is performed. 

Truncation takes effect immediately and differs from 
S$DELETE$FILE in this respect. A file cannot be deleted until 
all connections to the file have been severed. 



CALL RQ$S$TRUNCATE$FILE(connection, excep$ptr); 



INPUT PARAMETER 
connection 

excep$ptr 



is a token for an open connection to the 
file being truncated. 

is a pointer to the location that receives 
the condition code resulting from this 
call . 



FILE ACCESS REQUIREMENT 

The file to be truncated must be open for writing. 

CONDITION CODES 

E$OK, E$BAD$CALL, E$CONTEXT, E$EXIST, E$FACCESS, E$FLUSHING, 
E$IFDR, E$IO, E$LIMIT, E$MEM, E$NOT$CONFIGURED , E$TYPE. 
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S$WRITE$MOVE 

SYNCHRONOUS WRITE$MOVE SYSTEM CALL 

The S$WRITE$MOVE system call writes a collection of bytes from 
a user buffer to a designated file. The byte count returned 
equals the number of bytes requested unless an exceptional 
condition occurs. 



bytes$written = RQ$S$WRITE$MOVE(connection , buff$ptr, 

count, excepSptr) ; 



INPUT PARAMETERS 

connection is a token for the open connection to be 

written. 

buff$ptr is a pointer to the user buffer containing 

the data to be written. 

count is a word giving the number of bytes to be 

written. 

excepSptr is a pointer to the location that receives 

the condition code resulting from this 
call. 

RETURN VALUE 

bytes$written is a word giving the actual number of 

bytes written. 

FILE ACCESS REQUIREMENTS 

The caller must have update access to the file. The specified 
file must be open for writing. 

CONDITION CODES 

E$OK, ESBADBLK, E$BAD$CALL, E$CONTEXT, E$DEVNR, E$EXIST, 

ESFATALHW, E$FLUSHING, E$IO, E$LIMIT, E$MEM, E$MIXWRITEMODE , 

E$NOBUFF, E$NOT$CONFIGURED, E$NUMBUFF, E$PARITY, E$SPACE, 
E$SUPPORT, E$TYPE. 
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S$WRITE$UPDATE 



SYNCHRONOUS WRITE$UPDATE SYSTEM CALL 

The S$WRITE$UPDATE system call writes data from a specified 
SIOS buffer to an open composite connection* This call can be 
combined with a call to S$READ$LOCATE to update file 
information. 

A file update is initiated when S$READ$LOCATE reads data from a 
designated connection to the SIOS buffer specified by its 
"data$ptr" parameter S$READ$LOCATE. The data in the buffer can 
then be modified as necessary. Finally, S$WRITE$UPDATE is 
invoked to write data from the same SIOS buffer back to the 
same open connection. 

When the write operation has been completed, this call returns 
the actual number of bytes written. Normally, this count equals 
the number of bytes requested. The number of bytes requested, 
in turn, should be less than or equal to the number of bytes 
read by the preceding S$READ$LOCATE call. 



bytes$written = RQ$S$WRITE$UPDATE(connection, count, 

data$ptr, excep$ptr); 



INPUT PARAMETERS 



connection 



is a token for the open connection to be 
written. An S$READ$LOCATE call must have 
been the most recent operation on this 
connection. 



count 



excep$ptr 



is a word giving the number of bytes to be 
written. This value must be less than or 
equal to the value returned by the pre- 
ceding S$READ$LOCATE call. 

is a pointer to the location that receives 
the condition code resulting from this call. 



RETURN VALUE 

bytes$written is a word giving the actual number of bytes 
written. 

FILE ACCESS REQUIREMENTS 

The caller must have update access to the specified file. The 
file must be open for reading and writing. 

CONDITION CODES 

E$OK, E$BADBLK, E$BAD$CALL, E$CONTEXT, E$DEVNR, E$EXIST, 

E$FATAHW, E$FLUSHING, E$IO, E$LIMIT, E$MEM, E$NOBUFF, 

E$NOT$CONFIGURED, E$NREADLOCATE, E$NUMBUFF, E$PARITY, E$SPACE, 
E$SUPPORT, E$TYPE. 
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SUMMARY OF I/O SYSTEM CALLS 



This appendix summarizes RMX/86 I/O system calls by function 
and, where applicable, indicates the file types to which they 
apply: 



PF 
SF 
NF 
ND 



Physical file 
Stream file 
Named data file 
Named directory file 



The page reference listed with each call points to the PL/M 
calling sequence and detailed description for the call. 



JOB-LEVEL SYSTEM CALLS 



System Call 
CREATE$IO$JOB 
EXIT$IO$JOB 
SET$DEFAULT$PREFIX 
GET$DEFAULT$PREFIX 
SET$DEFAULT$USER 
GET$DEFAULT$USER 



Function Page 

Create job & initial task. 8-43 

Terminate job. 8-48 

Set default prefix for job. 8-83 

Inspect default prefix. 8-51 

Set default user for job. 8-84 

Inspect default user. 8-52 



GET TIME/DATE SYSTEM CALLS 



System Call 
GET$TIME 

GET$TIME$STRING 



Function Page 

Get date/time value in 8-53 
internally-stored format. 

Get date/time value in 8-54 
user-oriented format. 
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LOAD FILE/TASK SYSTEM CALL 

System Call Function Page 

S$LOAD Synchronous load. 8-93 

CREATE-FILE-CGNNECTION SYSTEM CALLS 



System Call Function P S N N Page 

F F F D F 

A$CREATE$FILE Asynchronous data * ^ ^ 3_i5 

file creation. 

H$CREATE$FILE Hybrid data-file * * * 8-60 

creation. 

S$CREATE$FILE Synchronous data- * * * 8-79 

file creation. 

A$ATTACH$FILE Asynchronous attach * * * * 8-8 

file. 

H$ATTACH$FILE Hybrid attach file. * * * ^ 8-53 

S$ATTACH$FILE Synchronous attach * * * Mr 8-72 

file. 

A$CREATE$DIRECTORY Asynchronous create * 8-13 

directory. 

H$CREATE$DIRECTORY Hybrid create * 8-38 

directory. 

S$CREATE$DIRECTORY Synchronous create * 8-77 

directory . 



FILE MODIFICATION SYSTEM CALLS 



System Call Function P S N N Page 

F F F D 



A$CHANGE$ACCESS Asynchronous change * * 8-10 

access rights to 
file. 
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FILE MODIFICATION SYSTEM CALLS (continued) 

P S N N Page 
F F F D 

H$CHANGE$ACCESS Hybrid change access * * 8-56 

rights to file. 

S$CHANGE$ACCESS Synchronous change * * 8-7A 

access rights to 
file. 

A$RENAME$FILE Asynchronous rename * * 8-35 

file. 

H$RENAME$FILE Hybrid rename file. * * 8-70 

S$RENAME$FILE Synchronous rename * * 8-104 



FILE INPUT/OUTPUT SYSTEM CALLS 

System Call Function P S N N Page 

F F F D 



A$OPEN Asynchronous open * * * 8-31 

file. 

S$OPEN Synchronous open ^ ^ ^ 3.99 

file . 

A$SEEK Asynchronous move * * 8-37 

file pointer. 

S$SEEK Synchronous move * * 8-105 

file pointer. 

A$READ Asynchronous read * * * 8-33 

file. 

S$READ$LOCATE Synchronous read * * * 8-101 

to SIOS buffer. 

S$READ$MOVE Synchronous read to * * * 8-103 

caller buffer. 

A$WRITE Asynchronous write * * * 8-41 

file. 

S$WRITE$MOVE Synchronous write * * * 8-109 

from caller buffer. 
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FILE INPUT/OUTPUT SYSTEM CALLS (continued) 

P S N N Page 
F F F D 

S$WRITE$UPDATE Synchronous write * * * 8-110 

from SIOS buffer 
used by S$READ$- 
LOCATE. 

A$CLOSE Asynchronous close * * * 8-11 

file. 

S$CLOSE Synchronous close * * * 8-76 

file . 



DEVICE-LEVEL FUNCTION SYSTEM CALLS 



System Call Function P S N N Page 

F F F D 



A$SPECIAL Asynchronous perform * 8-38 

device-level function. 

S$SPECIAL Synchronous perform * 8-106 

device-level function. 



GET STATUS/ATTRIBUTE SYSTEM CALLS 



System Call Function P S N N Page 

F F F D 



A$GET$CONNECTION$STATUS Asynchronous get * * * * 8-21 

connection status. 

S$GET$CONNECTION$STATUS Synchronous get * * * 8-85 

connection status. 

A$GET$FILE$STATUS Asynchronous get * * * * 8-25 

file status. 

H$GET$FILE$STATUS Hybrid get file ^ * ^ Mr 8-64 

status . 

S$GET$FILE$STATUS Synchronous get * ^t * * 8-88 

file status. 
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GET STATUS/ATTRIBUTE SYSTEM CALLS (continued) 



P S N N Page 
F F F D 



A$GET$DIRECTORY$ENTRY Asynchronous * 8-23 

inspect directory 
entry . 

A$GET$PATH$CGMPONENT Asynchronous * * 8-30 

obtain path name 
from connection 
token. 

H$LOOK$UP$CONNECTION Hybrid obtain ^ ^ Mr * 8-69 

connection token 
from logical name. 

S$LOOK$UP$CONNECTION Synchronous ^ * * * 8-98 

obtain connection 
token from logical 
name . 



DELETE CONNECTION/FILE SYSTEM CALLS 



System Call Function P S N N Page 

F F F D 

A$DELETE$CONNECTION Asynchronous delete * * * * 8-18 

file connection. 

H$DELETE$CONNECTION Hybrid delete file * * * * 8-62 

connection . 

S$DELETE$CONNECTION Synchronous delete * * * 8-81 

high-level file 
connection. 

A$TRUNCATE Asynchronous * 8-40 

truncate file. 

S$TRUNCATE$FILE Synchronous * 8-108 

truncate file. 

A$DELETE$FILE Asynchronous ^ ^ ^ 8-19 

delete file. 

H$DELETE$FILE Hybrid delete ^ ^ ^ 8-63 

file. 

S$DELETE$FILE Synchronous delete ^ * * 8-82 

file. 
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PL/M EXTERNAL PROCEDURES 



This appendix lists the PL/M external procedures declared for 
the I/O system calls described in this manual. The procedures 
are listed in the same sequence as the system call descriptions 
in Chapter 8. 

rq$a$attach$file: PROCEDURE(user , prefix, path$p, resp$mbox, 

excep$p) EXTERNAL; 



END 



DECLARE 
user 
prefix 
path$p 
respSmbox 
excep$p 
rq$a$attach$file; 



WORD, 

WORD, 

POINTER, 

WORD, 

POINTER: 



rq$a$change$access: PROCUEDURE(user , prefix, path$p, id, 

access, resp$mbox, excep$p) 
EXTERNAL: 



DECLARE 




user 


WORD, 


prefix 


WORD, 


path$p 


POINTER, 


id 


WORD, 


access 


BYTE, 


resp$mbox 


WORD, 


excep$p 


POINTER: 


END rq$a$change$access; 




rq$a$close: PROCEDURE(conn , 


respSmbox, 


DECLARE 




conn 


WORD, 


resp$mbox 


WORD, 


excepSp 


POINTER; 


END rq$a$close; 





excepSp) EXTERNAL; 



rq$a$create$directory : PROCEDURE(user , prefix, 

owner$access , 



END 



DECLARE 
user 
prefix 
pathSp 

owner$access 
respSmbox 
excepSp 
r qSaScre at e$di rectory ; 



excepSp) 



pathSp, 
respSmbox, 
EXTERNAL; 



WORD, 

WORD, 

POINTER, 

BYTE, 

WORD, 

POINTER; 
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rq$a$create$file : PROCEDURE(user, prefix, path$p, owner$access , 

gran, high$size, low$size, 
must$create, respSmbox, excep$p) 
EXTERNAL; 



DECLARE 




user 


WORD, 


prefix 


WORD, 


path$p 


POINTER, 


owner$access 


BYTE, 


gran 


WORD, 


high$size 


WORD, 


low$size 


WORD, 


must$create 


BYTE, 


resp$mbox 


WORD, 


excep$p 


POINTER; 


rq$a$create$file; 





END 



rq$a$delete$connection: PROCEDURE(conn , resp$mbox, excep$p) 

EXTERNAL; 
DECLARE 

conn WORD, 

resp$mbox WORD, 

excep$p POINTER; 

END rq$a$delete$connection; 

rq$a$delete$file: PROCEDURE(user , prefix, path$p, resp$mbox, 

excep$p) EXTERNAL; 
DECLARE 

user WORD, 

prefix WORD, 

path$p POINTER, 

respSmbox WORD, 

excep$p POINTER; 

END rq$a$delete$file; 

rq$a$connection$status : PROCEDURE(conn, resp$mbox, excep$p) 

EXTERNAL; 
DECLARE 

conn WORD, 

respSmbox WORD, 

excepSp POINTER; 

END rqSaSconnectionSstatus; 

rqSaSgetSdirectorySentry : PROCEDURE(conn, entrySnum, respSmbox, 

excepSp) EXTERNAL; 
DECLARE 

conn WORD, 

entrySnum WORD, 

respSmbox WORD, 

excepSp POINTER 

END rqSaSgetSdirectorySentry; 



f 
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rq$a$get$file$status : PROCEDURE(conn , resp$mbox, excep$p) 

EXTERNAL; 
DECLARE 

conn WORD, 

resp$mbox WORD, 

excep$p POINTER; 

END rq$a$get$file$status; 

rq$a$get$path$component : PROCEDURE(conn , resp$mbox, excep$p) 

EXTERNAL; 
DECLARE 

conn WORD, 

resp$mbox WORD, 

excepSp POINTER; 

END rq$a$get$path$component ; 



rq$a$open: PROCEDURE(conn , mode, share, resp$mbox, excepSp) 

EXTERNAL; 
DECLARE 

conn WORD, 

mode BYTE, 

share BYTE, 

respSmbox WORD, 

excep$p POINTER; 
END rq$a$open; 



rq$a$special$: PROCEDURE(conn, spec$func, parms$p , resp$mbox , 

excepSp) EXTERNAL; 
DECLARE 

conn WORD, 

spec$func WORD, 

parms$p POINTER, 

resp$mbox WORD, 

excep$p POINTER; 

END rq$a$special$; 



rq$a$read: PROCEDURE(conn , buff$p, count, resp$mbox, excep$p) 

EXTERNAL; 
DECLARE 

count WORD, 

conn WORD, 

buff$p POINTER, 

resp$mbox WORD, 

excep$p POINTER; 
END rq$a$read; 
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rq$a$rename$file: PROCEDURE(conn , user, prefix, path$p, 

resp$mbox, excepSp) EXTERNAL; 
DECLARE 

conn WORD, 

user WORD, 

prefix WORD, 

path$p POINTER, 

resp$mbox WORD, 

excepSp POINTER; 

END rq$a$rename$file; 

rq$a$seek: PROCEDURE(conn , mode, hi$ptr$move, low$ptr$move , 

resp$mbox, excepSp) EXTERNAL; 
DECLARE 

conn WORD, 

mode BYTE, 

hi$ptr$move WORD, 

low$ptr$move WORD, 

resp$mbox WORD, 

excepSp POINTER; 
END rq$a$seek; 

rq$a$truncate$: PROCEDURE(conn , resp$mbox, excep$p) EXTERNAL; 
DECLARE 

conn WORD, 

resp$mbox WORD, 

excepSp POINTER; 

END rq$a$truncate$file; 

rq$a$write: PROCEDURE(conn, buff$p, count, resp$mbox, excep$p) 

EXTERNAL; 
DECLARE 

conn WORD, 

buff$p POINTER, 

count WORD, 

resp$mbox WORD, 

excep$p POINTER; 

END rq$a$write; 

rq$create$IO$job: PROCEDURE( job$p , task$addr, stackSp, 

prefix$p, log$name$p, msg$mbox, 
excepSp) WORD EXTERNAL; 
DECLARE 

job$p POINTER, 

task$addr POINTER, 

StackSp POINTER, 

prefixSp POINTER, 

log$name$p POINTER, 

msg$mbox WORD, 

excep$p POINTER; 

END rq$create$IO$job; 
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rq$delete$package: PROCEDURE (package, excepSp) EXTERNAL; 
DECLARE 

package WORD, 

excepSp POINTER; 

END rq$delete$package; 

rq$exit$IO$job: PROCEDURE(user$exception$code , return$data, 

return$data$len, excep$p) EXTERNAL; 
DECLARE 

user$exception$code WORD, 
return$data POINTER, 

return$data$len WORD, 
excepSp POINTER; 

END rq$exit$IO$job; 

rq$get$default$prefix: PROCEDURE( JGb$t , excep$p) WORD EXTERNAL; 
DECLARE 

job$t WORD, 

excepSp POINTER; 

END rq$get$default$prefix ; 

rq$get$default$user: PROCEDURE( job$t , excep$p) WORD EXTERNAL; 
DECLARE 

job$t WORD, 

excepSp POINTER; 

END rq$get$default$user ; 

rq$get$time: PROCEDURE (excepSp) DWORD EXTERNAL; 
DECLARE 

excep$p POINTER; 

END rq$get$time; 

rq$get$time$string: PROCEDURE(dt$p, excep$p) EXTERNAL; 
DECLARE 

dt$p POINTER, 

excepSp POINTER; 

END rq$get$time$string ; 

rq$h$attach$file: PROCEDURE(l$name , path, excep$p) WORD 

EXTERNAL; 
DECLARE 

llname POINTER, 

path POINTER, 

excep$p POINTER; 

END rq$h$attach$file; 
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rq$h$change$access : PROCEDURE(path , mode, name, access, excep$p) 

EXTERNAL; 
DECLARE 

path POINTER, 

mode BYTE, 

name POINTER, 

access BYTE, 

excep$p POINTER; 

END rq$h$change$access ; 



rq$h$create$directory : PROCEDURE(l$name, path, excepSp) WORD 

EXTERNAL; 
DECLARE 

l$name POINTER, 

path POINTER, 

excep$p POINTER; 

END rq$h$create$directory ; 

rq$h$create$file: PROCEDURE(l$name , path, excep$p) WORD 

EXTERNAL; 
DECLARE 

l$name POINTER, 

path POINTER, 

excep$p POINTER; 

END rq$h$create$file; 



rq$h$delete$connection: PROCEDURE(conn , excep$p) EXTERNAL; 
DECLARE 

conn WORD, 

excepSp POINTER; 

END rq$h$delete$connection; 



rq$h$delete$file: PROCEDURE(path , excep$p) EXTERNAL; 
DECLARE 

path POINTER, 

excepSp POINTER; 

END rq$h$delete$file; 

rq$h$get$file$status: PROCEDURE(path , file$info$p, excepSp) 

EXTERNAL; 
DECLARE 

path POINTER, 

file$info$p POINTER, 

excepSp POINTER; 

END rqShSgetSfileSstatus; 
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rq$h$look$up$connection: PROCEDURE(l$name , excep$p) WORD 

EXTERNAL; 
DECLARE 

l$name POINTER, 

excepSp POINTER; 

END rq$h$look$up$connection; 



rq$h$rename$file: PROCEDURE(old$path , new$path, excep$p) 

EXTERNAL; 
DECLARE 

oldSpath POINTER, 

newipath POINTER, 

excep$p POINTER; 

END rq$h$rename$file; 

rq$inspect$package : PROCEDURE(package, tok$list$p, excepSp) 

EXTERNAL; 
DECLARE 

package WORD, 

tok$list$p POINTER, 

excepSp POINTER; 

END rq$inspect$package; 

rq$s$attach$file: PROCEDURE(l$name , path, buff$size, num$buff, 

excepSp) WORD EXTERNAL; 
DECLARE 

iSname POINTER, 

path POINTER, 

buffSsize WORD, 

numSbuff BYTE, 

excepSp POINTER; 

END rqSsSattachSfile; 

rqSsSchangeSaccess : PROCEDURE (path , mode, name, access, excepSp) 

EXTERNAL; 
DECLARE 

path POINTER, 

mode BYTE, 

name POINTER, 

access BYTE, 

excepSp POINTER; 

END rqSsSchangeSaccess; 

rqSsSclose: PROCEDURE(conn, excepSp) EXTERNAL; 
DECLARE 

conn WORD, 

excepSp POINTER; 

END rqSsSclose; 
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rq$s$create$directory : PROCEDURE(l$name , path, excepSp) 

WORD EXTERNAL; 
DECLARE 

l$name POINTER, 

path POINTER, 

excep$p POINTER; 

END rq$s$create$directory 

rq$s$create$file: PROCEDURE (l$name , path, buff$size, num$buff, 

excepSp) WORD EXTERNAL; 
DECLARE 

l$name POINTER, 

path POINTER, 

buff$size WORD, 

num$buff BYTE, 

excep$p POINTER; 

END rq$s$create$file ; 

rq$s$delete$connection: PROCEDURE(conn , excep$p) EXTERNAL; 
DECLARE 

conn WORD, 

excepSp POINTER; 

END rq$s$delete$connection ; 

rq$s$delete$file: PROCEDURE(path, excep$p) EXTERNAL; 
DECLARE 

path POINTER, 

excxepSp POINTER; 

END rq$s$delete$file; 

rq$set$default$prefix: PROCEDURE( job$t , prefix, excepSp) 

EXTERNAL; 
DECLARE 

job$t WORD, 

prefix WORD, 

excep$p POINTER; 

END rq$set$default$prefix; 

rq$set$default$user: PROCEDURE( job$t , user, excep$p) EXTERNAL; 
DECLARE 

job$t WORD, 

user WORD, 

excep$p POINTER; 

END rq$set$default$user ; 
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rq$s$get$connection$status : PROCEDURE(conn , conn$info$p, 

excepSp) EXTERNAL; 
DECLARE 

conn WORD, 

conn$info$p POINTER, 

excep$p POINTER; 

END rq$s$get$connection$status ; 

rq$s$get$file$status: PROCEDURE(path, file$info$p, escep$p) 

EXTERNAL; 
DECLARE 

path POINTER, 

file$info$p POINTER, 

excep$p POINTER; 

END rq$s$get$file$status; 



rq$s$load: PROCEDURE(path , load$func, job$data$p, reg$val$p, 

excep$p) WORD EXTERNAL; 
DECLARE 

path POINTER, 

load$func BYTE, 

job$data$p POINTER, 

reg$val$p POINTER, 

excep$p POINTER; 
END rq$s$load; 

rq$s$look$up$connection: PROCEDURE (l$name, excep$p) WORD 

EXTERNAL; 
DECLARE 

l$name POINTER, 

excepSp POINTER; 

END rq$s$look$up$connection; 

rq$s$open: PROCEDURE(conn, mode, share, buff$size, num$buff, 

excepSp) EXTERNAL; 
DECLARE 

conn WORD, 

mode BYTE, 

share BYTE, 

buff$size WORD, 

num$buff BYTE, 

excepSp POINTER; 
END rq$s$open; 
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rq$s$read$locate: PROCEDURE(conn, data$p, count, excep$p) WORD 

EXTERNAL; 
DECLARE 

conn WORD, 

data$p POINTER, 

count WORD, 

excep$p POINTER; 

END rq$s$read$locate; 

rq$s$read$move: PROCEDURE(conn, buff$p, count, excep$p) WORD 

EXTERNAL; 
DECLARE 

conn, WORD, 

buff$p POINTER, 

count WORD, 

excepSp POINTER; 

END rq$s$read$move; 

rq$s$rename$file : PROCEDURE(old$path , new$path, excep$p) 

EXTERNAL; 
DECLARE 

old$path POINTER, 

new$path POINTER, 

excep$p POINTER; 

END rq$s$rename$file ; 

rq$s$seek: PROCEDURE(conn, mode, hi$ptr$move, low$ptr$move , 

excepSp) EXTERNAL; 
DECLARE 

conn WORD, 

mode BYTE, 

hi$ptr$move WORD, 

low$ptr$move WORD, 

excep$p POINTER; 
END rq$s$seek; 

rq$s$special : PROCEDURE(conn, spec$func, parms$p, ioresp$p, 

excepSp) EXTERNAL; 
DECLARE 

conn WORD, 

spec$func WORD, 

parms$p POINTER, 

iorespSp POINTER, 

excep$p POINTER; 

END rq$s$special ; 

rq$s$truncate$file: PROCEDURE(conn , excep$p) EXTERNAL; 
DECLARE 

conn WORD, 

excepSp POINTER; 

END rq$s$truncate$file; 
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rq$s$write$move : PROCEDURE(conn , buff$p, count, excepSp) WORD 

EXTERNAL; 
DECLARE 

conn WORD, 

buff$p POINTER, 

count WORD, 

excep$p POINTER; 

END rq$s$write$move ; 

rq$s$write$upclate: PROCEDURE(conn, count, excep$p) WORD 

EXTERNAL; 
DECLARE 

conn WORD, 

count WORD, 

excep$p POINTER; 

END rq$s$write$upclate ; 
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I/O REQUEST/RESULT SEGMENT 



An I/O request/result segment is a data structure used to 
request I/O from a device driver and to indicate completion of 
an asynchronous I/O system call. Only the designer of a device 
driver needs to be concerned with the interpretation of this 
structure beyond its first three fields. Consequently, only the 
first three fields are defined below. 

When a task makes an asynchronous system call, it expects a 
connection or an I/O result segment to be returned to the 
mailbox specified by the "resp$mbox" parameter. The I/O result 
segment includes a status field containing "E$OK" if the call 
was completed successfully, or an asynchronous exceptional- 
condition code if an error occurred. The result segment also 
contains the actual number of bytes read or written, if 
appropriate. 



SEGMENT STRUCTURE 

The I/O request/result segment is structured as follows 

DECLARE 

iors STRUCTUREC 

status WORD, 

unit$status WORD, 

actual WORD, 

actual$fill WORD, 

device WORD, 

unit BYTE, 

func BYTE, 

spec$func WORD, 

dev$loc DWORD, 

buff$ptr POINTER, 

count DWORD, 

aux$ptr POINTER, 

linkSfor POINTER, 

linkSback POINTER, 

respSmbox WORD, 

done BYTE 

); 



SEGMENT STRUCTURE (continued) 
where: 



status 



indicates how the operation completed. 
"E$OK" indicates successful completion; 
"E$IO" indicates an error condition. 
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SEGMENT STRUCTURE (continued) 
where : 



unit$status 



actual 



contains device-dependent error code infor- 
mation and is valid only if status = E$IO. 
The codes that can be returned to this field 
are listed in the next section of this 
appendix . 

is the actual number of bytes transferred. 



STATUS CODES 

The following table lists the asynchronous exceptionalcondition 
codes returned in the status field of the I/O result segment. 
The table lists the condition codes, their hexadecimal equiv- 
alents, and their interpretations. 



Condition Code 


Hex 


E$OK 


OOOOH 


E$CONTEXT 


0005H 


E$DEVFD 


0022H 


E$DIR$$END 


0025H 


E$EMPTY$ENTRY 


0024H 


E$FACCESS 


0026H 


E$FEXIST 


0020H 


E$FLUSHING 


002CH 


E$FNEXIST 


0021H 


E$FTYPE 


0027H 


E$IDDR 


002AH 


E$IO 


002BH 


E$LIMIT 


0004H 


E$MEM 


0002H 


E$SHARE 


0028H 


E$SPACE 


0029H 


E$SUPPORT 


0023H 



Interpretation 
System call was completed successfully 
System call invoked in illegal context 
Device and file driver incompatibility 
End of directory. 
Empty directory entry. 
Access to file not granted. 
File already exists. 
Connection is flushing requests. 
File does not exist. 
Incompatible file type. 
Illegal Device Driver Request. 
I/O error. 

Object limit reached. 
Insufficient memory. 
Improper file sharing requested. 
No space left. 
Unsupported request. 
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EXCEPTIONAL-CONDITION CODES 

The I/O system checks for exceptional conditions when a system 
call is invoked. When an exceptional condition occurs, the 
system issues a condition code describing the error, then 
either returns to the caller or passes control to an exception 
handler. 

Exceptional-condition codes returned asynchronously (that is, 
returned in an I/O result segment) are listed in Appendix C. 
This appendix lists the codes for the exceptional conditions 
detected synchronously with system call invocation. These codes 
are returned to the location addressed by the "excep$ptr" field 
of the external-procedure declaration associated with each call 
(see Appendix B). The codes are listed below with the hexa- 
decimal equivalents and their interpretations. 

PROGRAMMING ERRORS 



Interpretation 

Call invoked illegally. 

Illegal file driver request. 

Job containing other jobs tried 
to exit. 

READ$LOCATE and READ$MOVE on 
same connection. 

WRITE$MOVE and WRITE$UPDATE on 
same connection. 

Not high-level user object. 

No SIOS buffers specified. 

No default prefix. 

No default user. 

WRITE$UPDATE not preceded by 
READS LOCATE. 

Too many SIOS buffers specified. 



Condition 


Code 


Hex 


E$BAD$CALL 




8005H 


E$IFDR 




8020H 


E$JNEXIT 




0040H 



ESMIXREADMODE 



80454 



E$MIX$WRITE$MODE 8046H 



E$NHUSER 




E$NOBUFF 


0045H 


E$NOPREFIX 


8022H 


E$NOUSER 


8021H 


E$NREADLOCATE 


0049H 


E$NUMBUFF 


0046H 
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PROGRAMMING ERRORS (continued) 



Condition Code Hex 

E$PARAM 8004H 

E$PREFIX$SYNTAX 80ABH 

D$NAME$USED 80ACH 

E$NOT$DEV$NAME 8040H 

E$NOT$CONN$NAME 804EH 

E$TYPE 8002H 



Interpretation 
Illegal parameter. 
Illegal prefix syntax. 
Name already in use. 
Not a valid device name. 
Not a valid connection name. 
Specified object is wrong type 



ENVIRONMENTAL CONDITIONS 



E$CANNOT$CLOSE 



0044H 



E$CONTEXT 


0005H 


E$EXIST 


0006H 


E$FACCESS 


0026H 


E$FEXIST 


0020H 


E$FNEXIST 


0021H 


E$FTYPE 


0027H 


E$LIMIT 


0004H 


E$MEM 


0002H 


E$NOT$CONFIGURED 


0008H 


E$SPACE 


0029H 


E$SUPPORT 


0023H 



Asynchronous I/O error while 
closing file. 

Call invoked in illegal context. 

Object referenced by token does 
not exist. 

File access not granted. 

File already exists. 

File does not exist. 

Incompatible file type. 

Calling job or system has 
reached object limit. 

Insufficient memory. 



No space left. 

Combination of parameters not 
supported. 
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LOADER CONDITION CODES 

The following condition codes are unique to the loader and are 
returned by calls S$LOAD. 



Condition Code Hex 

E$ABS$ADDRESS 0060H 

E$BAD$GRP 0061H 

E$BAD$HDR 0062H 

E$BAD$SEG 0063H 

E$CHECKSUM 0064H 

E$EOF 0065H 

E$FIXUP 0066H 

E$LFUNC 0067H 

E$NO$LMEM 0068H 

E$NO$MEM 0069H 

E$REC$FMT 006AH 

E$REC$LENGTH 006BH 

E$REC$TYPE 006CH 

E$REG$INIT 006DH 

E$SEG$ALLOC 006EH 



Interpretation 

Invalid absolute load address. 

Invalid group definition record. 

Invalid header record in object 
file. 

Invalid segment definition record. 

Checksum error. 

Unexpected end of file. 

Invalid fixup. 

Invalid load function requested. 

Insufficient memory to run loader. 

Insufficient memory to load and 
run task. 



Unspecified 
record . 



error in object 



Ivalid record length. 

Invalid object-record type. 

Uninitialized register detected; 
task is not created. 

Segment allocation error. 
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GLOSSARY 

ACCESS MASK. A byte specifying the access rights to a file. 
Each bit set to one permits the corresponding access. Possible 
values are: 



Bit 



Named Data Files 






Delete 


1 


Read 


2 


Append 


3 


Update 


4-7 


Reserved 



Named Directory Files 

Delete 

Display 

Add Entry 

Change Entry 

Reserved 



CONDITION CODE. A code returned when a system call is issued. 
"E$OK" indicates successful completion of the call. All other 
codes indicate exceptional or error conditions. 

CONNECTION. An RMX/86 object established when a device is 
attached (device connection) or a file is created or attached 
(file connection). A connection contains information needed to 
access the device or file, or to perform I/O on the file. 

DEFAULT PREFIX. A user-specified parameter (token for a con- 
nection) which can serve as the "prefix" parameter in system 
calls issued within the job where the default prefix is 
specified. 

DEFAULT USER. A user-specified parameter (token for a user 
object) which can serve as the "user" parameter in system calls 
issued within the job where the default user is specified. 

DEVICE. Any of a broad spectrum of traditional and non- 
traditional physical units, such as a line printer or 
thermistor . 

DIRECTORY FILE. A named file whose entries include the names 
of other directories or named data files and information for 
accessing these files. 

EXCEPTIONAL CONDITION. A condition indicating a result other 
than successful completion of a system call. The I/O system 
flags this situation by issuing an exceptional-condition code. 

FILE-ACCESS PROTECTION. The I/O system mechanism that limits 
access to named files to certain specified users. The specific 
access rights granted to these users can be limited also, (see 
ACCESS MASK). 

FILE DESCRIPTOR. An I/O system internal structure containing 
information about named files. 
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FILE GRANULARITY. The size (in bytes) of each logical block to 
be allocated to a file (for any allocations after its initial 
preallocation) . 

FILE NAME. A 1-14 ASCII-characater name used to designate a 
named file. This is the last name in the subpath string speci- 
fied when the file is created. The file name is cataloged in 
the file's parent directory. 

JOB. An operating environment and resource bank for tasks. 

LOGICAL NAME. A 1-12 ASCII-character symbolic name assigned to 
a connection object or user object at the hybrid or synchronous 
levels of I/O operation. This name can be used instead of a 
token to refer to these objects in subsequent system calls. 

LOGICAL-NAME DIRECTORY. A job-level directory used to catalog 
logical names. 

NAMED FILE. A collection of bytes residing on a random-access 
storage device. A named file can be either a data file or a 
directory file. 

PARAMETER. An item in a PL/M system call syntax description, 
to be replaced with an acutal value when the call is issued. 

PARENT DIRECTORY. That directory containing the file name and 
access information for a given file. 

PATH. The parameter(s) specified to locate a named file within 
a directory tree. It consists of PREFIX and a SUBPATH . 

PHYSICAL FILE. A file associated with a physical device other 
than a random-access storage device. 

PREFIX. A parameter containing a token for a connection or the 
logical name for such a token. In the case of a physical or 
stream file, or where the SUBPATH parameter is null in a ref- 
erence to a named file, the prefix specifies a file being 
accessed. If the SUBPATH is not null, the prefix indicates the 
starting point in a directory tree search for the named file 
being accessed. (See SUBPATH). 

RESPONSE MAILBOX. A mailbox used at the asynchronous level to 
synchronize I/O operations. The result of an asynchronous 
system call is returned to a response mailbox designated by the 
caller. 

RESULT SEGMENT. A status segment returned to a designated 
RESPONSE MAILBOX when an asynchronous system call has completed 
operation . 
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ROOT DIRECTORY. The base directory in a hierarchical directory 
tree. 

STREAM FILE. A file mechanism allowing tasks to communicate 
with one another without the intervention of external devices 
or media. 

SUBPATH. A parameter that points to a string describing the 
route from the starting point in a directory tree (designated 
by a PREFIX parameter) to the named file being sought. If 
subpath points to a null string, the PREFIX itself designates 
the desired file. (See PATH and PREFIX). 

SYSTEM CALL. The means by which the applications programmer 
accesses the facilities of the RMX/86 I/O system. 

TASK. The active principle within a job that performs the 
operations required of the job. 

TOKEN. A 16-bit item used to designate an RMX/86 object. Users 
exchange tokens in system calls to gain access to these 
objects. (See CONNECTION and USER OBJECT). 

USER OBJECT. An RMX/86 object that includes not only the 
identification of a given user, but also identifies all groups 
to which he belongs. 

VOLUME. The physical storage medium used by a random-access 
storage device, such as a diskette or hard-disk platter. 

VOLUME LABEL. A record on a volume containing information 
needed to support hierarchical directory trees and named files. 
This label is used internally by the I/O system. 
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